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PREFACE 


This manual contains a comprehensive description of the PDP-11l 
BASIC-PLUS language as implemented on the Resource-Sharing Time- 
Sharing System, RSTS-1l. Information is organized for the benefit 
of the beginning programmer, as it allows the reader to gradually 


acquire increased programming capabilities. 


A companion volume, the RSTS-11 System User's Guide, describes on- 
line operation of the RSTS-11 system as well as various useful sys- 
tem details. 


The BASIC-PLUS language is an extension of BASIC! as originally 
developed at Dartmouth College. The experienced BASIC programmer may 
find the appendices sufficient for his use. However, BASIC-PLUS 
offers many features not found in standard Dartmouth BASIC or any 
other version of BASIC. 


BASIC-PLUS incorporates the following special features: 


1. Matrix Computations: a set of 13 commands is avail- 
able for performing matrix computations. 


2. Alphanumeric String Capabilities: alphabetic and/or 
alphanumeric strings can be manipulated with the same 
ease as numeric data. Individual characters within 
these strings can be accessed by the user. 


3. Program Control and Storage Facilities: facilities 
are included for storing both programs and data on 
any mass storage device (such as DECdisk or DECtape) 
and later retrieving them for use during program 
execution. Programs can be entered from the RSTS 
terminal paper tape reader as well as from the high- 
speed paper tape reader available on the computer. 


Lack of data storage facilities has always hampered 
BASIC from becoming as useful a language as, for 
example, FORTRAN. With this ability and the ease of 
learning the BASIC language, the new user has an ex- 
tremely powerful tool at his command. 


'BASIC is a registered trademark of the Trustees of Dartmouth College. 
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Program Editing Facilities: an existing program can 
be edited by adding or deleting lines, or renaming 

the program. The user can combine two programs into 
a single program and request the listing of a program, 
either in whole or in part on his terminal or on a 
line printer. 


Formatting of Output: controlled formatting of pro- 
gram output includes facilities for tabs, spaces, 

and the printing of column headings, as well as pre- 
cise specifications of the output line formatting and 
floating dollar sign, asterisk fill, and comma inser- 
tion in numeric output. 


Immediate Mode of Operation: commands typed by the user 
are immediately executed by BASIC-PLUS instead of being 
stored for later execution. 


Access to System Peripheral Equipment: the user pro- 
gram is able to perform input and output with various 
equipment, such as paper tape reader/punch, disk, DEC- 
tape, industry-compatible magnetic tape, line printer, 
and card reader. (Details on device operation can be 


found in the RSTS-11 System User's Guide.) 


Record I/O: language extensions provide a means of 
handling records composed of fixed-length fields in 
a highly efficient manner. 


Documentation and Debugging Aids: the insertion of 
remarks and comments within a program is simple in 
this version of BASIC. Debugging of programs is 
aided by the printing of meaningful diagnostic mes- 
sages which pinpoint errors detected during the pro- 
gram execution. 
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SOFTWARE SUPPORT CATEGORIES 


Digital Equipment Corporation (DEC) makes available four categories of software. These 
categories reflect the types of support a customer may expect from DEC for a specified software 
product. DEC reserves the right to change the category of a software product at any time. 

The four categories are as follows: 


CATEGORY | 
Software Products Supported at no Charge 


This classification includes current versions of monitors, programming languages, and 
support programs provided by DEC. DEC will provide installation (when applicable), advisory, 
and remedial support at no charge. These services are limited to original purchasers of DEC 
computer systems who have the requisite DEC equipment and software products. 

At the option of DEC, a software product may be recategorized from Category | to 
Category Il for a particular customer if the software product has been modified by the customer 
or a third party. 


CATEGORY II 
Software Products that Receive Support for a Fee 


This category includes prior versions of Category | programs and all other programs avail- 
able from DEC for which support is given. Programming assistance (additional support), as 
available, will be provided on these DEC programs and non-DEC programs when used in con- 
junction with these DEC programs and equipment supplied by DEC . 


CATEGORY III 
Pre-Release Software 


DEC may elect to release certain software products to customers in order to facilitate 
final testing and/or customer familiarization. In this event, DEC will limit the use of such 
pre-release software to internal, non-competitive applications. Category III software is only 
supported by DEC where this support is consistent with evaluation of the software product. 
While DEC will be grateful! for the reporting of any criticism and suggestions pertaining to a 
pre-release, there exists no commitment to respond to these reports. 


CATEGORY IV 
Non-Supported Software 


This category includes all programs for which no support is given. 
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PART I 


RSTS-11 AND THE BASIC-PLUS LANGUAGE 


This first Part describes the RSTS-11 system, its hardware and 
user features, and the simplest level of the BASIC language. BASIC 
as described here is essentially Dartmouth BASIC as originally 
developed. Part II describes the extended capabilities of BASIC- 
PLUS. As part of the introductory material, the reader will find 
references to some of the extended capabilities. Part III describes 
the complete range of BASIC-PLUS I/O, including record I/O and 


information on particular I/O devices. 


As a language, BASIC is easy to learn. BASIC-PLUS provides 
many advanced features which allow BASIC to be a useful tool for 
the more experienced programmer. BASIC does not, however, penal- 
ize the beginning user. Almost any problem can be solved with the 
statements available in Part I. The statements and features in 
Parts IE and III allow the user to write more efficient code to 


better use machine time and core space. 


CHAPTER 1 


AN INTRODUCTION TO RSTS~11 


In this manual, the RSTS-11 user need only be concerned with 
the writing and execution of correct programs in the BASIC-PLUS 
language. A description of the various RSTS-11 commands (NEW, OLD, 


LIST, RUN, etc.) can be found in the RSTS-11 System User's Guide. 


1.1 INTRODUCTION TO PROGRAMMING 
For the benefit of the new programmer approaching his first com- 


puting experience, there are four phases in programming a computer: 


a. writing the computer program, 
b. entering the program to the computing system, 
c. testing and debugging the program, and 


d. running the finished program. 


BASIC-PLUS is the language in which the user writes programs de- 
signed for the RSTS-1l1 system. Input of the completed program is 
generally performed from the terminal keyboard on RSTS-11. 

A program can be input through various peripheral devices, such as 
the paper tape reader, magnetic tape, DECtape, or punched cards; how- 
ever, the initial creation of a BASIC program is usually performed 
on-line to the computer from the terminal keyboard. 


Ideally a program runs correctly as written; but in practice 
this is seldom the case. A program can contain simple typing mis- 
takes or complex logical errors. Typing and syntactical errors are 
detected as the program is typed at the keyboard and appropriate er- 
ror messages are printed. BASIC-PLUS also evaluates the entire pro- 
gram for commonly made errors and generates messages which explain 
the mistakes to the user. Program errors are corrected on-line from 
the terminal keyboard. 


The testing and debugging process is continued until the program 
appears to execute correctly. This is a good time to explain to the 
new user that a computer program only does what the programmer has 


written. The calculations performed by the computer are not necessar- 
ily those that will produce the correct results. In order to obtain 
correct results from a computer, the user must write a program which 
is not only free of detectable errors, but one which correctly ana- 


lyzes his problem, 


RSTS-11 provides keyboard commands which enable the user not 
only to create and execute his program but also to save the program 
within the system for later retrieval and execution or modification. 


This saving process is known as storing or filing the program. 


1.2 INTRODUCTION TO TIME~SHARING 
RSTS-11 is a time-sharing system. This means that when a user 
is working with RSTS, he has the illusion that he is the only user on 


the computer, 


Many users can be on-line to RSTS at one time because RSTS con- 
trols the scheduling of execution times, RSTS has one or more users 
in core at one time. Users are brought into core from disk, allowed 
to execute for a short time, and returned to disk. This process is 
called swapping. RSTS takes note of the state at which execution 


stops and is able to resume operation at that point. 
1 
Fach user is allotted a block of core between 2K and 8K for stor- 


age of his particular program. This block is swapped between core 
and disk. If only one user job is active in the system at a given 
time, that job is allowed to execute without interruption until 


another program is ready. 


1.3 THE BASIC-PLUS PROGRAMMING LANGUAGE 

BASIC is one of the simplest of all programming languages because 
of the small number of powerful but easily understood statements and 
commands and its easy application to problem solving, The wide use 
of BASIC in scientific, business, and educational installations at- 
tests to its value and straightforward application. (For a bibliog- 
raphy of texts on BASIC and other elementary computing texts, see 
Appendix G,) 


BASIC is similar to many other programming languages in various 
respects but is especially suited for time-sharing because of its 
conversational nature. A conversational language is one which allows 
the user to communicate with the language processor by typing on the 
terminal keyboard. BASIC responds by printing on the terminal, 


1 
The term "K" refers to 1924 (decimal) words of storage in a computer 
Hence, 2K=2$48 words and 8k=8192 words. 
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providing for an interactive man/machine relationship. 


BASIC-PLUS contains both the elementary statements used to write 
Simple programs and many new advanced programming features and state- 
ments to produce more complex and efficient programs. The key word 
here is efficient. As the user progresses and gains programming ex- 
perience, he will naturally find himself becoming more efficient and 
able to use the more sophisticated data manipulations. Almost any 
problem can be solved with the simple PASIC statements. Later in the 


user's programming experience, the advanced techniques can be added. 


1.4 CONVENTIONS USED IN THIS MANUAL 
ee MANUAL 


Certain documentation conventions are used throughout this manual 
to clarify examples of BASIC Syntax. Each BASIC statement is de- 
scribed at least once in general terms using the following conven- 


tions: 


a. Items in italic type (formula, vartable, etc.) are supplied 
by the user according to rules explained in the text. Items 
in capital letters (LET, IF, THEN, etc.) must appear exactly 


as shown because they form the vocabulary of the BASIC language. 


b. The term line number used in examples indicates that any 
line number is valid. 


on Angle brackets indicate essential elements of the statement 
or command being described. For example: 


line number{LET}<vartable> = <expression> 
d. Square brackets indicate a choice of one element among two 


Or more possibilities. For example: 


THEN <statement> 
line number IF <expression> | THEN <line number> 
GOTO <line number> 


e. Braces indicate an optional statement element or a choice 
of one element among two or more optional elements: 


THEN <statement> ; ELSE <statement> 4 
line number IF <expresston> THEN <Zine number>|' ELSE <line number> 
GOTO <Zine number> 


The use of some terms in this document may be unfamiliar to the 
new user. The following definitions and explanations are valid 
throughout this manual: 


a. BASIC prints on the teleprinter whereas the user types 
on the keyboard. 


b. A statement is a single BASIC language instruction. Each 
BASIC program line is preceded by a line number and termi- 
nated by the RETURN key. A program line may contain a 
single statement or several statements separated by colons 
(see Section 2.3.1). 


Cc. Commands cause BASIC to perform some operation im- 
mediately and are not preceded by a line number. 
A command is terminated by typing the RETURN key. 


d. A user program consists of a series of statements 
written by a person using the BASIC-PLUS language. 


e. The RSTS-1l terminal is in most cases an ASR-33 
aor . 
Teletype‘. However, RSTS-11 can accommodate a wide 


variety of other terminals such as a DECwriter or 
VT@5 display. The RSTS-11 user terminal is alter- 
natively referred to as terminal, teleprinter, or 
keyboard, depending upon whether a part or the 
whole device is indicated. The use of terminals 
and other peripheral devices is described in the 
RSTS-11 System User's Guide. 


f. The term BASIC is used interchangeably to indicate 
the BASIC language and the BASIC Interpreter (the 
system program which accepts and executes BASIC 
programs). 


el 


1 Teletype is a registered trademark of the Teletype Corporation. 


CHAPTER 2 


FUNDAMENTALS OF PROGRAMMING IN BASIC-PLUS 


2.1 EXAMPLE BASIC PROGRAM 

The program in Figure 2.1 is an example of a user program writ- 
ten in the BASIC-PLUS language. It illustrates the syntax and ele- 
ments of the language as well as standard formatting of statements 


and the appearance of terminal output. 


The user program (the lines numbered 10 through 200) may at this 
time mean little, although the remark in the first line (line 10) 
and the printed results (following the word RUNNH) show that the pro- 


gram computes interest payments. 


A user program is composed of lines of statements containing 
instructions to BASIC. Each line of the program begins with a line 
number that serves to identify that line as a statement and to in-~ 
dicate the order in which statements are to be evaluated for execution. 
Each statement starts with a word specifying the type of operation to 


be performed. 


2.2 LINE NUMBERS 
Each BASIC program line is preceded by a line number. Line 
numbers: 


a. indicate the order in which statements are normally 
evaluated; 
b. enable the normal order of evaluation to be changed; 


that is, the execution of the program can branch or 
loop through designated statements (this is explained 
further in the sections on the GOTO, GOSUB, and 
IF-~THEN statements in Chapter 3); and 


c. enhance program debugging by permitting modification 
of any specified line without affecting any other 
portion of the program. 


Line numbers are in the range 1 to 32767. BASIC maintains pro- 
grams in line number sequence, rather than the order in which lines 
are entered to the system. It is good programming practice to num- 
ber lines in increments of 5 or 10 when first writing a program, to 
allow for insertion of forgotten or additional lines when debugging 
the program. 


‘The syntax of a language is the collection of rules governing the 
combination of language elements. 
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LISTNH 


REMARK - THIS PROGRAM COMPUTES INTEREST PAYMENTS 
INPUT “INTEREST IN PERCENT” 3J 

LET J=J/198 

INPUT “AMOUNT OF LOAN’; A 

INPUT “NUMBER OF YEARS"s N 

INPUT "NUMBER OF PAYMENTS PER YEAR"; M 

LET N=NeMs I=J/M: B=1+I 

LET R=AxI/C1<-1/BTtN) 

PRINT 

PRINT * AMOUNT PER PAYMENT =" 


¢ INTCR*1@T2+.5)/18t2 
PRINT “TOTAL INTEREST 3 I 


NTC CREN-A)*10724+.5)/1872 


2 PRINT 


LET B=A 

PRINT "INTEREST APP TO PRIN BALANCE OF PRIN” 

LET L=B*I: P=R-L: B-B-P 

PRINT INTC(LHEL@T12+.5)/1872, INTC P¥1Ot2+.5)/1012, 
INT(B*¥1372+.5)/19T2 

IF B>=R GOTO 158 

PRINT INTC C(B*¥I)*18t72+.5)/18t2, INTCCR -B¥I)*1972+,.5)/1082 

PRINT "LAST PAYMENT ="3 INTC (B¥I+B)*1972+.5)/1912 

END 


RUNNH 

INTEREST IN PERCENT? 7.5 
AMOUNT OF LOAN? 2588 

NUMBER OF YEARS? 2 

NUMBER OF PAYMENTS PER YEAR? 4 


AMOUNT PER PAYMENT = 339.44 


TOTAL INTEREST 215.51 
INTEREST APP TO PRIN BALANCE OF PRIN 
46.88 292.56 2287.44 

41.39 298.85 1999.39 

35.8 303.64 1695.75 

32.11 389.33 1296, 42 

24.51 315.13 981.28 

18.4 321.84 669.24 

12,38 327.86 333.18 

6.25 333.19 


LAST PAYMENT = 339.43 


READY 


Figure 2-1 


Example BASIC Program 


When a program is executed (with the use of the RUN command), 
the BASIC processor evaluates the statements in the order of their 
line numbers, starting with the smallest line number and going to the 


largest. 


2.3 STATEMENTS 


Each line number is followed by a BASIC statement. The first 
word of a BASIC statement identifies the type of statement and informs 
BASIC of the operation to be performed and how to treat the data 
(if any) which follows the word. 


2.3.1 Multiple Statements on a Single Line 


More than one statement can be written on a single line as long 
as each statement (except the last) is terminated with a colon. Thus 
only the first statement on a line can (and must) have a line number. 
For example: 


1G INPUT A»BsC 


is a single statement line, while: 
eG LET X=K+l!: PRINT X%sYsZ: IF Y=o GOTO 14 


is a multiple-statement line containing three statements: a LET, a 
PRINT, and an IF-GOTO statement. 


Any statement can be used anywhere in a multiple-statement line 
except as noted in the discussion of the individual statements. 


2.3.2 A_Single Statement on Multiple Lines 


A single statement can be continued on successive lines of the 
program. To indicate that a statement is to be continued, the line 
is terminated with the LINE FEED key instead of the RETURN key. The 
LINE FEED performs a carriage return/line feed operation on the ter- 
minal and the line to be continued does not contain a line number. 
For example: 


1A LET GPS CUXA*Q eC Z-AL 
(A-R)-17) 


where the first line was terminated with the LINE FEED key is equiva- 
lent to: 
16 LET Y7SCy-X4e3)40Z-A/CA-BI-17) 


Note that the LINE FEED key does not cause a printed character to 
appear on the page. 


The length of a multiple-line statement is limited to 255 charac- 


ters. 2-3 


Where the LINE FEED key is used, it must occur between the ele- 
ments of a BASIC statement. That is, a BASIC verb or the designation 
of a subscripted array element (see Section 3.6.2), for example, 


cannot be broken with a LINE FEED. 


i@ IF Als? 
THEN Lad 


is acceptable where a LINE FEED follows 9, but: 


19 IF Als TH 


EN 104 
ILLEGAL IF STATEMENT AT LINE 14 


is not acceptable nor is: 


IF A 
t= THEN 149 
ILLFGAL CONDITIONAL CLAUSE 


nor is: 
1G IF Also THEN 1 


(Aer 


MODIFIER ERROR @T LINE 18 


and each illegal form will generate an error message. 


2.4 SPACES AND TABS 
Spaces can be used freely throughout the program to make state- 


ments easier to read. For example: 
14 LET R = D*e+1 
instead of: 
IGLETBHaD#2+1 


or 


i@ 3, BFTQ = DP) * Atl 
The above statements are identical in effect. 


TABS, like spaces, are used to make a program easy to read. 
An example follows: 


1% FOR K=1 TO 3 


aa FOR IT=1 TO 19 

39 FOR J=1 TO 14 

49 ACIsJ) = K/CIl+J-1)+ACIsJ) 
54 NEXT J 

64 NEXT I 

74 NEXT K 


2.5 EXPRESSIONS 
An expression is a group of symbols which can be evaluated by 
BASIC. Expressions are composed of numbers, variables, functions, or 


a combination of the preceding separated by arithmetic or relational 
operators. 


The following are examples of expressions acceptable to BASIC- 


PLUS: 
Arithmetic Expressions Logical Expressions 
: X<Y 
A7* (Bt2+1) ((A>B) OR (C=D)) AND A/B<>¢,?> 


Not all kinds of expressions can be used in all statements, as is cx- 
plained in the sections describing the individual statements. in the 
following sections the reader is introduced to the elements which 


compose BASIC expressions. 


2.5.1 Numbers 

Numbers, called numeric constants because they retain a constant 
value throughout a program, can be positive or negative. Appendix F 
explains the integer and floating-point number formats. Numeric 


constants are written using decimal notation, as follows: 


However, BASIC can find the decimal expansion of those two mathemati- 


cal formulas as shown below: 


14 


3 is expressed as 14/3 


Y 7 is expressed as SQR(7) 


These formats are explained in later sections. 


Scientific notation allows further flexibility in number 
representation. Numeric constants can be written using the 


letter E to indicate "times ten to the power," thus: 


- 9GG123456 can be written in BASIC as 123.456E-6 
1234569092. can be written in BASIC as 123456E4 
-12345678992. can be written in BASIC as -1.2345679E19 


The E format representation of numbers is very flexible since a number 
such as .001 can be written as 1E-3, .01E-1, 100E-5, or any number of 
ways. If more than six digits are generated during any computation, 
the result of that computation is automatically printed in E format. 
(If the exponent is negative, a minus sign is printed after the E; 


if the exponent is positive, a space is printed: 1E-#4; 1E 94.) 


The combination E7, however, is not a constant, but a variable. 


The term 1E7 is used to indicate that 1 is multiplied by 107, 


The range of floating-point numbers is (approximately) as follows: 


X=6 or in the range 107 38 < ABS(X) < ess 


2.5.2 Variables 


A variable is a data item whose value can be changed by the 
program. A numeric variable is denoted by a single letter or by a 
letter followed by a single digit. Thus BASIC interprets E8 as a 
variable, along with A, X, N5, L#, and Ol. (Subscripted, integer, and 


character string variables are described in later sections.) 


Variables are assigned values by LET, INPUT, and READ statements. 
The value assigned to a variable does not change until the next time 


a LET, INPUT or READ statement is encountered that contains a new 


value for that variable or when the variable is incremented by a FOR 
statement. (These conditions are explained further in later sections. 
All variables are set equal to zero (%) before program execution. 

It is only necessary to assign a value to a variable when an initial 
value other than zero is required. However, good programming prac- 
tice would be to set variables equal to % wherever necessary. This 


ensures that later changes or additions will not misinterpret values. 


2.5.3 Mathematical Operators 


BASIC automatically performs the mathematical operations of ad- 
dition, subtraction, multiplication, division and exponentiation. 
Formulas to be evaluated are represented in a format similar to stan- 
dard mathematical notation. There are five arithmetic operators used 


to write such formulas; they are as follows: 


Operator Example Meaning 
+ A+B Add B to A 
- A-B Subtract B from A 
* A*B Multiply A by B 
A/B Divide A by B 
+ AtB Calculate A to the B power, a® 


BASIC-PLUS permits the operator ** in place of + to denote the 


exponentiation operation. For example: 
A*®*B 


indicates the quantity A raised to the B power, es The ** operator 
is included for compatibility with some other BASIC processors. The 
symbol + is generally considered the BASIC symbol for exponentiation 


and is used throughout this manual. 


Unary plus and minus are also allowed, e.g. the - in -A+B or the 
+ in +X-Y. Unary plus is ignored. Unary minus is treated as explained 


below. 


When more than one operation is to be performed in a single formu- 
la, as is most often the case, rules are observed as to the precedence 
of the above operators. The arithmetic operations are performed in 


the following sequence, with (a) having the highest precedence: 
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a. Any formula within parentheses is evaluated before the 
parenthesized quantity is used in further computations. 
Where parentheses are nested, as follows: 

(A+ (B* (D+2))) 
the innermost parenthetical quantity is calculated first. 

b. In the absence of parentheses in a formula, BASIC performs 

operations as follows: 


l. exponentiation 

2. unary minus 

3. multiplication and division 
4. addition and subtraction 


Thus, for example, -AtB with a unary minus, is a legal 

expression and is the same as -(A+B). This implies that 
-2+2 evaluates as -4. The one extension of this rule is 
that the term A+-B is allowed and is evaluated as At+(-B). 


c. In the absence of parentheses in a formula involving more 
than one operation on the same level in (b) above, the 
operations are performed left to right, in the order that 
the formula is written. For example: 


A/B/C is evaluated as (A/B)/C 
A*B/C is evaluated as (A*B)/C 
The expression A+B*CtD is evaluated as follows: 
first, C is raised to the D power 
second, the result of the first operation is multiplied by B 
third, the result of the previous operation is added to A. 


Parentheses are used to indicate any other order of evaluation. For 
example, if it is the product of B and C that is to be raised to the 


D power, the expression would look as follows: 


A+ (B*C) tD 


If it is desired to multiply the quantity A+B by C to the D power: 
(A+B) *CtD 


The user is encouraged to use parentheses even where they are not 
strictly required in order to make ~xpressions easier to read. Am- 
biguities can exist only in the programmer's mind, the computer always 


performs the operations as explained above. 


2.5.4 Relational Symbols 


Relational symbols are used in IF-THEN statements (see Section 3.5); 
in conditional FOR loops (see Section 8.6); and in IF, UNLESS, WHILE 
and UNTIL clauses (see Sections 3.5, 8.5, and 8.7) where it is neces- 
sary to compare values. The relational symbols are as follows (where 


A and B are variables or expressions): 


Mathematical BASIC 


Symbol Symbol Example Meaning 
= = A=B A is equal to B 
< < A<B A is less than B 
‘ <= A<=B A is less than or equal to B 
> > A>B A is greater than B 
> >= A>=B A is greater than or equal to B 
# <> A<>B A is not equal to B 
x == A== A is approximately equal to B. 


The term "approximately equal to" means that the two quantities 

lock the same when printed. Within the computer, floating-point 
numbers can differ by a miniscule amount in the last decimal place 
but still be considered equal for all practical purposes. This last 
decimal place within the computer does not always cause two numbers 

to have a different value when printed. Numbers are carried inter- 
nally at greater than 6 digits of precision, but are rounded to 6 
digits for output or a * comparison. Thus, two numbers identical 
when rounded to 6 digits of precision are approximately equal, whereas 
two numbers equal to the internally carried limits of precision are 


truly equal (=). 


250<D Logical Operators 


Logical operators are used in IF-THEN and such statements (see 
Section 3.5) where some condition is used to determine subsequent 
Operations within the user program. The logical operators are as 


follows (where A and B are relational expressions) : 


Operator Example Meaning 
NOT NOT A The logical negative of A. If A is true, 


NOT A is false. 


AND A AND B The logical product of A and B. A AND B has 
the value true only if A and B are both true 
and has the value false if either A or B is 
false. 


OR A OR B The logical sum of A and B. A ORB has the 
value true if either A or B is true and has 
the value false only if both A and B are 
false. 


XOR A XOR B The logical exclusive OR of A and B. A XOR B 
is true if either A or B is true but 
not both, and false otherwise. 


IMP A IMP B The logical implication of A and B. A IMP 
B is false if and only if A is true and B is 
false; otherwise the value is true. 


EQV A EQV B A is logically equivalent to B. A EQV B has 
the value TRUE if A and B are both true or 
both false, and has the value false otherwise. 


The following tables are called truth tables and describe graphi- 
cally the results of the above logical operations with both A and B 
given for every possible combination of values. In logical operations, 


the only possible values a term can have are true and false (T and F). 


CHAPTER 3 


ELEMENTARY BASIC STATEMENTS 


This Chapter describes the simplest forms of the more elementary 
BASIC statements. These statements are sufficient, by themselves, for 
the solution of most problems. Once these statements are mastered, 
the user can investigate the more advanced applications of these state- 
ments and the additional statements and features explained in Parts 
II and Ili. 


The reader should understand that any problem which can be 
solved with the more advanced techniques can also be solved with the 
simpler statements, although the solution may not be as efficient. 
As long as the user understands the details of his problem he can 
represent it in BASIC on a number of levels ranging from the simple 
to the sophisticated. 


3.1 REMARKS AND COMMENTS 

It is often desirable to insert notes and messages within a user 
program. Such data as the name and purpose of the program, how to 
use it, how certain parts of the program work, and expected results at 
various points are useful things to have present in the program for 


ready reference by anyone using that program. 
There are two ways of inserting comments into a user program: 


a. the REMARK statement, and 
b. use of the exclamation mark (!) 


The word REMARK can be abbreviated to REM for typing convenience, 
and the message itself can contain any printing characters on the key- 
board. BASIC completely ignores anything on a line following the let- 
ters REM. (The line number of a REM statement can be used in a GOTO 
or GOSUB statement, see Sections 3.4 and 3.8.1, as the destination of 


a jump in program execution.) Typical REM statements are shown below: 


14 REM = THIS PROGRAM COMPUTES THE 
11 REM - ROOTS OF A QUADRATIC EQUATION 


The exclamation mark is normally used to terminate the executable 
part of a line and begin the comment part of the line. The ! character 
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can also begin the line, in which case the entire line is treated as a 
comment. For example: 

125 LET As8+4*SERCC) 'SET A EQUAL TO INITIAL VALUE 

139 PRINT A/eat+l !'PRINT SECOND CALCULATED VALUE 

146 !COMMENT 


In every statement other than the DATA statement, BASIC ignores every- 
thing on the line following the exclamation mark. An exclamation mark 
must not appear on the same line as a DATA statement unless it is part 
of an item in the DATA statement. (Tabs are useful for inserting space 


between the statement and comment parts of a line to improve readability.) 


Messages in REMARK statements are generally called remarks, those 
after the exclamation mark, comments. Remarks and comments are printed 


when the user program is listed but do not affect program execution. 


The lines below indicate three ways of putting the same remark on 
two lines. Lines 10 and 11 are REM statements. Line 20 is one REM 
statement broken into two lines with the LINE FEED key. Line 30 is 
one comment (begun with a !) and broken into two lines with the LINE 
FEED key. 


14 REM THIS PROGRAM COMPUTES THE 
11 RRM ROOTS OF A QUADRATIC EQUATION 


20 REM THIS PROGRSM COMPUTES THE 
ROOTS OF A QUADRATIC EQUATION 


36 1 THIS PROGRAM COMPUTES THR 
ROOTS OF A QUADRATIC EQUATION 


3.2 LET STATEMENT 
The LET statement assigns a numeric value to a variable. Each 


LET statement is of the form: 


line number{LET}<variable>=<expresston> 


This statement does not indicate algebraic equality, but performs the 
calculations within the expression (if any) and assigns the numeric 
value to the indicated variable. For example: 

ia LET X=x+1 

PA LET Ye=CA4-K13)*(Z-A/B) 
In line 10, the old value of X is increased by one and becomes the new 
value of X. In line 20, the formula on the right hand side is evalu- 


ated and the numeric value assigned to W2. 
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The LET statement can be a simple numerical assignment, such as 
5@ LET A=35 


or require the evaluation of a formula so long that it is continued on 


the next line (see Section 2.3.2). 


BASIC-PLUS allows the user to completely omit the word LET from 


the LET statement. The user may find it easier to type: 
16 K=12*(S+7) 

than 
19 LET X=12*¢S+7) 


This is a convenience and does not alter the effect of the statement. 


The LET statement can be used anywhere in a multiple statement 


line, for example: 


10 X=442 Y=Xt2A+Yls3 Be=3.5%*A 


The LET statement allows the user to assign a value to multiple 
variables in the same statement. For example: 


16 LET XsYsZ = Sef 


causes each of the three variables to be set equal to 5.7. 


3.3 PROGRAMMED INPUT AND OUTPUT 


This Section describes the techniques used in performing BASIC 
program I/O (an abbreviation for the term Input/Output which includes 
the processes by which data is brought into and sent out of the computer). 
The most elementary forms of the PRINT, INPUT, READ, and DATA statements 
are presented here so that the user is able to create simple BASIC 
programs, 


Using the LET statement, already described, and the following 
executable statements, the user can easily write a BASIC progran, 
If he should want to try his program, these simple I/O statements 
provide a means of obtaining tangible output. 


More advanced I/O techniques are described in Part III. 


3.3.1 READ, DATA, and RESTORE Statements 

READ and DATA statements are used to enter information into the 
user program during execution. A READ statement is used to assign to 
the listed variables those values which are obtained from a DATA state- 
ment. Neither statement is used without the other. 


A READ statement is of the form: 


line number READ <vartable list> 
A DATA statement is of the form: 


Line number DATA <value ltst> 


A READ statement causes the variables listed to be assigned se- 
quential values in the collection of DATA statements. Before the 
program is run, BASIC takes all DATA statements in the order they 
appear and creates a data block. Each time a READ statement is 
encountered in the program, the data block supplies the next value. 
If the data block runs out of data, the program is assumed to be fin- 
ished and an OUT OF DATA message is printed by BASIC. 


READ and DATA statements appear as follows: 


154 READ Xo¥sZsoKlsyYes9 
B38 DATA AsRalel 
340 DATA Ge f(34E-Ss -1l¥4e3el>s 3Be141592/ 


Note that only numbers are used in this particular DATA statement. 
(Input of string data is treated in Section 5.3.) The assignments 
performed by line 15% are as follows: 


KOS 
ou 


nN & 


Z=1.7 
X1=6.734E3 
Y¥2=-174.321 
Q9=3.1415927 


Since data must be read before it can be used in a program, READ 
statements normally occur near the beginning of a program. The loca- 
tion of DATA statements is arbitrary, as long as they occur in the 


correct order. A good practice is to collect all DATA statements 


near the end of the program. A DATA statement must be the only state- 
ment or the last statement on a line, while a READ statement can be 


placed anywhere in a multiple statement line. 


NOTE 


Comments are not permitted at the end of 
a DATA statement. 


If it should become necessary to use the same data more than 
once in a program, the RESTORE statement makes it possible to recycle 
through the complete set of DATA statements in that program, beginning 
with the lowest numbered DATA statement. The RESTORE statement is of 


the form: 


line number RESTORE 
For example: 


30 RESTORE 


causes the next READ statement following line 3f to begin reading data 
from the first DATA statement in the program, regardless of where the 


last data value was found. 


The same variable names can be used the second time through the 
data or not, as is most convenient, since the values are being read 
as though for the first time. In order to skip unwanted values, dummy 
variables must be read. In the following example, BASIC prints: 


4 1 2 3 


on the last line because it did not skip the value for the original 
N when it executed the loop beginning at line 45. 


LISTNH 

19 REM PROGRAM TO ILLUSTRATE USE OF RESTORE 
15 READ N: PRINT “VALUES OF X ARE:” 

2@ FOR I=! TO Nz: READ Xt: PRINT Xx, 

25 NEXT I 

32 RESTORE 

35 PRINT: PRINT "SECOND LIST OF X VALUES” 
48 PRINT "FOLLOWING RESTORE STATEMENT:" 

45 FOR I=1 TO Ns READ X: PRINT x, 


58 NEXT I 
68 DATA 4,1,2 
70 DATA 3,4 
88 END 
REALY 
RUNNH 
VALUES OF ¥ ARE: 
1 2 3 4 


SECOND LIST OF X VALUES 
FOLLOWING RESTORE STATEMENT: 
1 


4 2 3 
READY 
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When reading a BASIC program from the terminal paper tape reader 
often the last line read is the READY printed by BASIC when the pro- 
gram was listed (and punched on the tape at the same time). BASIC 
interprets this as a READ Y command (in immediate mode) and, if there 


are no DATA statements in the program, gives an "OUT OF DATA" message. 


3.3.2 PRINT Statement 
The PRINT statement is used to output data onto the terminal 
teleprinter. The general format of the PRINT statement is: 


line number PRINT {list} 


where the list can contain expressions, text strings, or both. As 
the braces indicate, the list is optional. Used alone, the PRINT 


statement: 
25 PRINT 


causes a blank line to be printed on the teleprinter (a carriage 


return/line feed operation is performed). 


PRINT statements can be used to perform calculations and print 
results. Any expression within the list is evaluated before a value 
is printed. Consider the following program: 


LISTNH 
1@ LET A=l: LET B=2: LET C=34A 


2@ PRINT 
5@ PRINT A+B+C 
READY 
RUNNH 
T 


READY 
All numbers are printed in the form: 


space 
é pa 5 <number> <space> 


The PRINT statement can be used anywhere in a multiple statement 
line. For example: 


18 A=1: PRINT As: A=A+5: PRINT: PRINT A 


would cause the following to be printed on the terminal when executed: 


RUNNH 


READY 


Notice that the teleprinter performs a carriage return/line feed at the 
end of each PRINT statement. Thus the first PRINT statement causes a l 
and a carriage return/line feed, the second PRINT statement is respon- 
sible for the blank line, and the third PRINT statement causes a 6 and 


another carriage return/line feed to be output. 


BASIC considers the terminal printer to be divided into five zones 
of fourteen spaces each'. When an item in a PRINT statement is followed 
by a comma, the next value to be printed appears in the next available 


print zone. For example: 


19 LET A=3: LET B2 
20 PRINT A,B,A+B,A*B,A-B,B-A 


When the preceding lines are executed, the following is printed: 


H 2 5 6 | 


Notice that the sixth element in the PRINT list is printed as the 
first entry on a new line, since a 72-character line has five print zones. 


Two commas together in a PRINT statement cause a print zone to be 


skipped. For example: 


LISTNH 
18 LET Azl: LET B=2 
20 PRINT A,B,,A+B 


REABY 
RUNNH 
1 


READY 


If the last item in a PRINT statement is followed by a comma, no 
carriage return/line feed is output, and the next value to be printed 
(by a later PRINT statement) appears in the next available print zone. 
For example: 

LISTNH 


1@ A=1:B=2:C=3 
28 PRINT A,:PRINT Bz: PRINT C 


READY 
RUNNH 

| 2 
3 


READY 


‘Terminals with greater than 83 columns have additional print zones 
in units of fourteen spaces. 
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If a tighter packing of printed values is desired, the semicolon 
character can be used in place of the comma. A semicolon causes no 
further spaces to be output. A comma causes the print head to move 
at least one space to the next print zone or possibly perform a car- 
riage return/line feed. The following example shows the effects of 
the semicolon and comma. 


LISTNH 

1@ LET Azl: Bz2@s C23 
28 PRINT A3B3C; 

32 PRINT A+13B+13C+1 
4@ PRINT A,B,C 


READY 


RUNNH 
123 2 3 4 
1 2 3 


READY 


The PRINT statement can be used to print a message, either alone 
or together with the evaluation and printing of numeric values. Charac~ 
ters are indicated for printing by enclosing them in single or double 
quotation marks (therefore each type of quotation mark can only be 
printed if surrounded by the other type of quotation mark). For 


example: 


LISTNH 
19 PRINT “TIME’S UP" 
28 PRINT '“NEVERMORE™’ 


READY 

RUNNH 
TIME’S UP 
"NEVERMORE™ 


READY 


As another example, consider the following line: 
40 PRINT “AVERAGE GRADE IS3x 


which prints the following (where X is equal to 83.4): 


AVERAGE GRADE IS 834 


When a character string is printed, only the characters between 
the quotes appear; no leading or trailing spaces are added. Leading 
and trailing spaces can be added within the quotation marks using the 
keyboard space bar; spaces appear in the printout exactly as they are 
typed within the quotation marks. 
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When a comma separates a text string from another PRINT list item, 
the item is printed at the beginning of the next available print zone. 
Semicolons separating text strings from other items are ignored. Thus, 


the previous example could be expressed as: 


40 PRINT “AVERAGE GRADE IS" X 


and the same printout would result. A comma or semicolon appearing 
as the last item of a PRINT list always suppresses the carriage re- 
turn/line feed operation. 


The following example demonstrates the use of the formatting 
characters, and ; with text strings: 


129 PRINT “STUDENT NUMBER'Xs"GRADE ="G3"AUEs =A; 
139 PRINT "NO-e IN CLASS ="'N 


could cause the following to be printed (assuming calculations were 


done prior to line 130): 


STUDENT NUMBER 119054 GRADE = 87 AVE. = 85+¢44 NOe IN CLASS = 26 


3.3.3 INPUT Statement 

The second way to input data to a program is with an INPUT state- 
ment. This statement is used when writing a program to process data 
to be supplied while the program is running. During execution, the 
programmer can type values as the computer asks for them. (Non- 
terminal INPUT is described in Part III.) Depending upon how many 
values are to be accepted by the INPUT command, the programmer may 
wish to send himself a message reminding him what data is to be 
typed at what time (this can be done with the PRINT or INPUT statement). 


The INPUT statement is of the form: 
line number INPUT <list> 
For example: 


10 INPUT AsRsc 


causes the computer to pause during execution, print a question mark, 
and wait for the user to type three numeric values separated by 

commas. The values typed are entered to the computer by typing the 
RETURN key or the ESCAPE key (ESC on some terminals, ALT MODE on others). 


In the example program following, four questions are asked at 
execution time: INTEREST IN PERCENT?, AMOUNT OF LOAN?, NUMBER OF 
YEARS?, and NO. OF PAYMENTS PER YEAR?. The programmer knows which 
value is requested and proceeds to type and enter the appropriate 


value. 


LISTNH 

19 REM PROGRAM TO COMPUTE INTEREST PAYMENTS 
15 INPUT "INTEREST IN PERCENT"; J 

28 LET J=J/1@@ 

25 INPUT "AMOUNT OF LOAN"; A 

30 INPUT “NUMBER OF YEARS"; N 

35 INPUT "NO. OF PAYMENTS PER YEAR"; ™ 

AQ N=N&M: I=d/M: Bzl+I: R=A*I/C1-1/BtN) 

45 PRINT: PRINT "AMOUNT PER PAYMENT ="5R 

50 PRINT "TOTAL INTEREST =" sREN-A 

55 PRINT: B=A 

68 PRINT "INTEREST APP TO PRIN BALANCE OF PRIN" 
65 L=BxI: P=R-L: B-B-P 

$7 PRINT L,P,B 

7@ IF B>=R GOTO 65 

75 PRINT BeI,R-Bel 

30 PRINT “LAST PAYMENT WAS "B*I+B 

85 END 


READY 


RUNNH 

INTEREST IN PERCENT? 9 
AMOUNT OF LOAN? 2586 

NUMBER OF YEARS? 2 

NO. OF PAYMENTS PER YEAR? 4 


AMOUNT PER PAYMENT = 344.961 
TOTAL INTEREST = 259,688 


INTEREST APP TO PRIN BALANCE OF PRIN 


56.25 288.711 2211.29 
49.754 295.287 1916.88 
43.1119 581.849 1614.23 
36,5282 388.641 1305.59 
29.3758 315,585 998.687 
22.2752 322.686 667.521 
15.8147 329.946 337.375 
7.59893 337.37 


LAST PAYMENT WAS 344.966 
READY 


As in the previous program, the question mark generated by BASIC 
is grammatically useful if a printed question is to prompt the typing 
of the input values. 


The output for the program begins after the word RUNNH and in- 
cludes a verbal description of the numbers. This verbal description 
on the output is optional with the programmer, although it has a def- 
inite advantage in ease of use and understanding. 


When the correct number of variables have been typed in answer 
to the printed ? character, type the RETURN key to enter the values to 
the computer. If too few values are listed, the computer prints 
another ? to indicate that more data is requested. If too many values 
are typed, the excess data on that line is ignored. 


Messages to be printed at execution time can be inserted within 
the INPUT statement itself. The message is set off by single or dou- 
ble quotes from the other arguments of the INPUT statement. For example 


18 INPUT "YOUR AGE IS "3A 


is equivalent to 


1@ PRINT “YOUR AGE IS "3 
24 INPUT A 


The use of the comma or semicolon character (or no character) to 
separate a character string to be printed from input variable names is 
analogous to the PRINT statement (see Section 3.3.2). 


3.4 UNCONDITIONAL BRANCH, GOTO STATEMENT 

The GOTO statement is used when it is desired to unconditionally 
transfer to some line other than the next sequential line in the pro- 
gram. In other words, a GOTO statement causes an immediate jump to a 
specified line, out of the normal consecutive line number order of 
execution. The general format of the statement is as follows: 


line number GOTO <line number> 


The line number to which the program jumps can be either greater than 
or less than the current line number. It is thus possible to jump 
forward or backward within a program. 


Consider the following simple example: 


1@ LET A=2 

28 GOTO 58 

3@ LET A=SQR(A+14) 
5@ PRINT A,A*xA 


When executed, the above lines cause the following to be printed: 
2 4 


When the program encounters line 20, control transfers to line 50; 
line 50 is executed, control then continues to the line following line 
50. Line 30 is never executed. Any number of lines can be skipped in 


either direction. 


When written as part of a multiple statement line, GOTO should 
always be the last statement on the line, since any statement fol- 
lowing the GOTO on the same line is never executed. For example: 


119 LET ASATN(RB2): PRINT A: GOTO 54 


3.5 CONDITIONAL BRANCH, IF-THEN AND IF-GOTO STATEMENTS 
The IF-THEN and IF-GOTO statements are used to transfer condition- 
ally from the normal consecutive order of statement numbers, depending 
upon the truth of some mathematical relation or relations. The basic 
format of the IF statement is as follows: 
THEN<statement> 


line number IF <condtitton> THEN<Zine number> 
GOTO<Zine number> 


The specified condition is tested. If the relationship is found false, 
then control is transferred to the statement following the IF state- 
ment (the next sequentially numbered line). If the condition is true, 
the statement following THEN is executed or control is transferred to 
the line number given after THEN or GOTO. (An extension of this state- 
ment, the IF-THEN-ELSE statement, is described in Section 8.5.) 


The deciding condition can be either a simple relational expres- 
sion in which two mathematical expressions are separated by a rela- 
tional operator, or a logical expression in which two relational or 


logical expressions are separated by a logical operator. For example: 


Relational Expression Logical Expression 
A+2>B A>B AND B<=SQR(C) 


Both types of condition, when evaluated, are either true or false; no 
numeric value is associated with the results of an IF statement. The 
relational and logical operators are described in Sections 2.5.4 and 


2.5.5 and are presented in Appendix A for reference. 
75 IF A*B>=B*(B+1) THEN LET D4=D4+1 


In the above line the quantities A*B and B*(B+1l) are compared. If the 
first value is greater than or equal to the second value, the variable 
D4 is incremented by 1. If B*(B+l) is greater than A*B, D4 is not incre- 
mented and control passes immediately to the next line following line 75. 


When a line number follows the word THEN, the IF-THEN statement 
is the same as the IF-GOTO statement. The word THEN can be followed 
by any BASIC statement, including another IF statement. For example: 


25 IF A>B THEN IF B>C THEN PRINT "A>B>C" 
25 IF A>B AND BoC THEN PRINT “A>B>C" 


The preceding two lines are logically equivalent and perform the fol- 


lowing operation: 
if B is both less than A and greater than C, the message 
A>B>C 


is printed, otherwise the line following line 25 is executed. 


In the following example, the IF-GOTO statement in line 20 is 
used to limit the value of the variable A in line 10. Execution of 
the loop continues until the relationship A>4 is true, then immediately 
branches to line 55 to end the program. (A program loop is a series 
of statements which are written so that, when the statements have been 
executed, control transfers to the beginning of the statements. This 


process continues to occur until some terminal condition is reached. ) 


LISTNH 

10 LET Az=A+ls X=AtT2 

22 IF A>4 GOTO 55 

25 PRINT X 

38 PRINT “VALUE OF A IS” A 
49 GOTO 18 

55 END 


READY 


when the above loop is executed, the following is printed: 


RUNNH 
VALUE OF AIS 1 
VALUE OF AIS 2 
VALUE OF AIS 3 
VALUE OF A IS 4 
READY 


(The novice BASIC programmer is advised to follow the operation of the 


computer through these short example programs. ) 


In IF statements, the following priorities are associated with 
each operator, in order to provide unambiguous evaluation of the con- 


ditions specified (where a. has the highest priority): 


a. expressions in parentheses 

b. intrinsic or user-defined functions 

c. exponentiation (+) 

d. unary minus (-), that is, a negative number or 
variable such as -3, ~A, etc. 

e. multiplication and division (* and /) 

£. addition and subtraction (+ and -) 

g. relational operators (=, <, <=, >, >=, ==, <>) 

h. NOT 

i. AND 

j- OR and XOR 

k. IMP 

1. EQV 


Within the operators indicated in any one group above, operations pro- 


ceed from left to right. 


Examples of IF-THEN statements follow: 


10 IF A>B THEN 100 !SIMPLE COMPARISON 
20 IF A=B OR B=C THEN 200 
34 IF A>B THEN A=-B !ASSIGNMENT BY A LET STATEMENT 


460 IF X>Y IMP Y>Z THEN PRINT "QED" 


An IF statement would normally be the last statement on a multiple 
statement line (to avoid confusion); however, the following rules 
govern the transfer path of the IF statement in other positions: 


a. The physically last THEN clause is considered to be fol- 
lowed by the next statement (or statements) on the line: 


19 IF A=! THEN PRINT A3:3PRINT "TRUE CASE": GOTO 26 
15 PRINT “NOT = 1" 


where A#1l, the following line is printed: 
NOT =1 

where A=], the following line is printed: 
1 TRIE CASE 


b. All other THEN clauses are considered to be followed 
by the next line of the program: 


20 IF A>B THEN IF B>C THEN PRINT “BoC: GOTO 34 
25 PRINT “A<=B" 


Only in the case where "B>C" is printed is the state- 
ment GOTO 38 seen and executed. 


3.6 PROGRAM LOOPS 


Loops were first mentioned in the section on the IF-THEN 
and IF-GOTO statement. Programs frequently involve performing cer- 
tain operations a specific number of times. This is a task for which 
a computer is particularly well suited. With simple tasks, such as 
computing a list of prime numbers between 1 and 1,000,000, a computer 
can perform the operations and obtain correct results in a minimal 
amount of time. To write a loop, the programmer must ensure that the 
series of statements is repeated until a terminal condition is met. 


Programs containing loops can be illustrated by using two ver- 
sions of a program to print a table of the positive integers 1 through 
100 together with the square root of each. Without a loop, the first 
program is 101 lines long and reads: 


10 PRINT 15 SQRC1) 
26 PRINT 25 SORC2) 
38 PRINT 35 SQRC3) 


990 PRINT 995 S@R(99) 
1200 PRINT 1005 SQRC190) 
1819 END 


With the following program example, using a simple sort of loop, 
the same table is obtained with fewer lines: 


146 LET X=1 

20 PRINT XsSQRCX) 

30 LET X=X+1 

40 IF X<=100 THEN 26 
59 END 


Statement 10 assigns a value of 1 to X, thus setting up the initial 
conditions of the loop. In line 20, both 1 and its square root are 
printed. In line 30, X is incremented by 1. Line 40 asks whether X 
is still less than or equal to 100; if so, BASIC returns to print the 
next value of X and its square root. This process is repeated until 
the loop has been executed 100 times. After the number 100 and its 
square root have been printed, X becomes 101. The condition in line 40 
is now false so control does not return to line 20, but goes to line 50 
which ends the program. 


All program loops have four characteristic parts: 


a. initialization, the conditions which must exist for the 
first execution of the loop (line 10 above); 


b. the body of the loop in which the operation which is 
to be repeated is performed (line 20 above); 


c. modification, which alters some value and makes each 
execution of the loop different from the one before 
and the one after (line 30 above); 


d. termination condition, an exit test which, when satisfied, 
completes the loop (line 40 above). Execution continues to 
the program statements following the loop (line 50 above). 


3.6.1 FOR and NEXT Statements 
The FOR statement is of the form: 


line number FOR <variable>=<expression> TO <expression> {STEP <expresston>} 


For example: 


19 FOR K=2 TO 20 STEP 2 


which causes program execution to cycle through the designated loop 
using K as 2, 4, 6, 8,..., 20 in calculations involving K. When K=20, 
the loop is left behind and the program controlpasses to the line fol- 
lowing the associated NEXT statement. The variable in the FOR state- 
ment, K in the preceding example, is known as the control variable. 


The control variable must be unsubscripted, although a common use 
of such loops is to deal with subscripted variables using the control 
variable as the subscript of a previously defined variable (this is 
explained in further detail in Section 3.6.2). The expressions in the 
FOR statement can be any acceptable BASIC expression as defined in 


Section 2.5. 


The NEXT statement signals the end of the loop which began with 
the FOR statement. The NEXT statement is of the form: 


line number NEXT <vartable> 


where the variable is the same variable specified in the FOR statement. 
Together the FOR and NEXT statements describe the boundaries of the 
program loop. When execution encounters the NEXT statement, the com- 
puter adds the STEP expression value to the variable and checks to see 

if the variable is still less than or equal to the terminal expression 
value. When the variable exceeds the terminal expression value, con- 
trol falls through the loop to the statement following the NEXT statement. 


If the STEP expression is omitted from the FOR statement, +l is 
the assumed value. Since +l is a common STEP value, that portion of the 
statement is frequently omitted. 


The expressions within the FOR statement are evaluated once upon 
initial entry to the loop. The test for completion of the loop is made 
prior to each execution of the loop. (If the test fails initially, the 
loop is never executed.) 


The control variable can be modified within the loop. When control 
falls through the loop, the control variable retains the last value used 
within the loop. 


The following is a demonstration of a simple FOR-NEXT loop. The 
loop is executed 10 times; the value of I is 10 when control leaves the 
loop; and +1 is the assumed STEP value: 

10 FOR I=! TO 1@ 
20 PRINT I 


38 NEXT I 
4@ PRINT I 


The loop itself is lines 10 through 30. The numbers 1 through 10 are 
printed when the loop is executed. After I=10, control passes to line 
40 which causes 10 to be printed again. If line 10 had been: 


19 FOR I = 1@ TO 1 STEP -1 


the value printed by line 40 would be 1. 


1¢@ FOR 1 = 2 TO 44 STEP 2 
20 LET I = 44 
30 NEXT I 


The above loop is only executed once since the value of I=44 has been 


reached and the termination condition is satisfied. 


If, however, the initial value of the variable is greater than 
the terminal value, the loop is not executed at all. A statement 


of the format: 


19 FOR I = @@ TO 2 STEP 2 


cannot be used to begin a loop, although a statement like the follow- 


ing will initialize execution of a loop properly: 
19 FOR I=2@ TO 2 STEP -2 


For positive STEP values, the loop is executed until the control 
variable is greater than its final value. For negative STEP values, 
the loop continues until the control variable is less than its final 
value. 

FOR loops can be nested but not overlapped. The depth of nesting 
depends upon the amount of user storage space available {in other 
words, upon the size of the user program and the amount of core each 
Nesting is a programming technique in which one 
The field of one 


user has available). 
or more loops are completely within another loop. 
loop (the numbered lines from the FOR statement to the corresponding 
NEXT statement, inclusive) must not cross the field of another loop. 


ACCEPTABLE NESTING 


UNACCEPTABLE NESTING 


TECHNIQUES TECHNIQUES 
Two Level Nesting 
FOR Il = 117019 FOR Il = 1 TO 19 
ree. I2 = 1 TO 1g FOR I2 = 1 TO 19 
NEXT I2 NEXT I1 
mes I3=1tTo 1g NEXT I2 
NEXT 13 
NEXT Il 
Three Level Nesting 
FOR Il = 1 TO 1g FOR Il = 1 TO 19 
FOR I2 = 1 TO 19 FOR I2 = 1 TO 1g 
FOR I3 = 1 TO 19 FOR I3 = 1 TO 1g 
NEXT 13 NEXT 13 
FOR 14 = 1T0 19 FOR 14 = 1 TO 19 
NEXT 14 NEXT 14 
NEXT 12 NEXT [1 
NEXT Il NEXT 12 
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An example of nested FOR-NEXT loops is shown below: 


5 DIM XC€5s10) 

10 FOR A=l TO 5 

26 FOR B=2 TO 19 STEP 2 
30 LET XCAsB)= A+B 

42 NEXT B 

5@ NEXT A 

55 PRINT X(€5210) 


Upon execution of the above statements, BASIC prints 15 when line 


55 is processed. 


It is possible to exit from a FOR-NEXT loop without the control 
variable reaching the termination value. A conditional or uncondition- 
al transfer can be used to leave a loop. Control can only transfer 
into a loop which had been left earlier without being completed, en- 


suring that termination and STEP values are assigned. 


Both FOR and NEXT statements can appear anywhere in a multiple 


statement line. For example: 


i@ FOR T=! TO 16 STEP Ss: NEXT I: PRINT "I="3I 


causes: 


to be printed when executed. 


Neither the FOR nor NEXT statement can be executed conditionally in 
an IF statement. The following statements are incorrect: 


15 IF I<>J THEN NEXT I 
16 IF IT=J THEN FOR I=1 TO J 


3.6.2 Subscripted Variables and the DIM Statement 


In addition to the simple variables which were described in 
Chapter 2, BASIC allows the use of subscripted variables. Subscripted 
variables provide the programmer with additional computing capabili- 
ties for dealing with lists, tables, matrices, or any set of related 
variables. In BASIC, variables are allowed one or two subscripts. 


The name of a subscripted variable is any acceptable BASIC vari- 
able name followed by one or two integer expressions in parentheses. 


For example, a list might be described as A(I) where I goes from 1 


to 5 as shown below (all matrices are created with a zero element, 


even though that element is never specified): 
A(@), A(1), A(2), A(3), A(4), A(5) 
This allows the programmer to reference each of six elements in the 


list, which can be considered a one dimensional algebraic matrix as 


follows: 


A two dimensional matrix B(I,J) can be defined in a similar man- 


ner and graphically illustrated as follows: 


TEED 
oh ee 


——_] 


a, 
a eee ee ee ee 


Subscripts used with subscripted variables throughout a program can 
be explicitly stated or be any legal expression. 


It is pdssible to use the same variable name as both a sub- 
scripted and an unsubscripted variable. Both A and A(I) are valid 
variables and can be used in the same program. However, BASIC does 
not accept the same variable name as both a singly and a doubly sub- 
scripted variable name in the same program (A(I) and A(I,8) would 
refer to the same data item). 


A dimension (DIM) statement is used to define the maximum 
number of elements in a matrix. ("Matrix" is the general term 
used in this manual to describe all the elements of a subscripted 
variable.) The DIM statement is of the form: 
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line number DIM <vartiable (n)>,<variable(n,m)>,... 


Where the variables specified are indicated with their maximum sub- 


script value(s). 


For example: 


10 DIM X€5)5 YC4s2)s ACIGs10) 
12 DIM 14¢18@) 


Only integer values (such as 5 or 5070) can be used in DIM 
statements to define the size of a matrix. Any number of matrices 
can be defined in a single DIM statement as long as their 


representations are separated by commas. 


If a subscripted variable is used without appearing in a DIM 
statement, it is assumed to be dimensioned to length 10 in each dimen- 
sion (that is, having eleven elements in each dimension, @ through 19). 
However, all matrices should be correctly dimensioned in a program. 
DIM statements are usually grouped together among the first lines of 


a program. 


The first element of every matrix is automatically assumed to 
have a subscript of zero. Dimensioning A(6,10) sets up room for a 
matrix with 7 rows and 11 columns. This zero element is illustrated 


in the following program: 


LISTNH 

1@ REM - MATRIX CHECK PROGRAM 
20 DIM AC6,1@) 

38 FOR I=@ TO 6 

4@ LET ACI,@) = 1 

5@ FOR J=@ TO 19 

68 LET AC@,J) = J 

78 PRINT ACI,J)3 

89 NEXT J: PRINT: NEXT I 

98 END 


READY 
RUNNH 


AW baNe 
]oaoan Qa — 
QQ Q ® ® @ vy 
® ® ® © ® @ w 
2 Oa ® © & bb 
RQoaaaggu 
Ql ® SBA 
®]eH OH Oa & ~) 
2a ® QS 7 
Hf ® BO 
]eQ ® © ® 8 — 


READY 


Notice that a variable has a value of zero until it is assigned a 


value. 


If the user wishes to conserve core space he may make use of 
the extra variables set up within the matrix. He could, for 
example, say DIM A(5,9) to obtain a 6 x 10 matrix which would then 
be referenced beginning with the A(@,#) element. 


The size and number of matrices which can be defined depend 


upon the amount of user storage space available. 


Additional information on matrices can be found in Chapter 7. 


A DIM statement can be placed anywhere in a multiple statement 
line. A DIM statement can appear anywhere in the program and need 
not appear prior to the first reference to an array, although DIM 
statements are generally among the first statements of a program 
to allow them to be easily found if any alterations are later 


required. 


3.7 MATHEMATICAL FUNCTIONS 


Within the course of a user's programming experience, he 
encounters many cases where relatively common mathematical operations 
are performed. The results of these common operations can often he- 
found in volumes of mathematical tables; i.e., sine, cosine, square 
root, log, etc. Since it is this sort of operation that computers 
perform with speed and accuracy, such operations are built into 
BASIC. The user need never consult tables to obtain the value of 
the sine of 23° or the natural log of 144. When such values are 


to be used in an expression, intrinsic functions, such as: 


SIN (23*PI/18f) 
LOG (144) 


are substituted. 


The various mathematical functions available in BASIC-PLUS 
are detailed in Table 3.1. 


Table 3.1 
Mathematical Functions 


Function 
Code Meaning 


ABS (X) returns the absolute value of xX 
SGN (X) returns the sign function of X, a value 
of 1 preceded by the sign of X, SGN(@)=9 
returns the greatest integer in X which is 
less than or equal to X, (INT(-.5)=-1) 
returns the truncated value of X, 
SGN (X) * INT (ABS (X)) , (FIX (-.5) =9) 
returns the cosine of X in radians 


INT (X) 


FIX(X) 


COS (X) 


SIN (X) returns the sine of X in radians 

TAN (X) returns the tangent of X in radians 

ATN (X) returns the arctangent (in radians) of x 

SOR (X) returns the square root of X 

EXP (X) returns the value of etX, where e=2.71828... 
LOG (X) returns the natural logarithm of X, log_Xx 
LOG1@ (X) returns the common logarithm of X, logy gx 


has a constant value of 3.1415927 
returns a random number between § and 1; 
the same sequence of random numbers is 
generated each time a program is run 
requiring the use of the random number 
generator. The value of X is ignored. 
alternate form for calling the random number 
function. 


Most of these functions are self-explanatory. Those which are 
not are explained in the following section. 


3031 Examples of Particular Intrinsic Functions 


Siyn Function, SGN(X) 


The sign function returns the value +1 if X is a positive value, 
fp if X is M, and -1 if X is negative. For example: SGN (3.42) = 1, 


SGN (-42) = -1, and SGN(23-23) = g. 
LISTNH 
1@ REM - SGN FUNCTION EXAMPLE 
20 READ A,B 


25 PRINT “A="A,”"B="B 

30 PRINT “SGN(A)="SGNCA),” SGN(B) =" SGN (B) 
A® PRINT “SGNCINTCA)>="SGNCINTCA)) 

58 DATA -7.32, 2 44 

66 END 


READY 

RUNNH 

Az=-7,32 B= 044 
SGNCA)=-1 SGN(B)= 
SGNCINT(A)) 2-1 


REABY 


Integer Function, INT(X) 
The integer function returns the value of the greatest integer 


not greater than X. For example, INT(34.67) = 34. INT can be used 
to round numbers to the nearest integer by asking for INT(X+.5). For 
example, INT(34.67+.5) = 35. INT can also be used to round to any 
given decimal place, by asking for 


INT (X*19+ D+.5)/1g+tD 


where D is the number of decimal places desired, as in the following 


program: 


LISTNH 

19 REM- INT FUNCTION EXAMPLE 

29 PRINT “NUMBER TO BE ROUNDED"; 
38 INPUT A 

4@ PRINT "NO. OF DECIMAL PLACES"; 
56 INPUT D 


68 LET B=INTCA*®10TB+.5)/101B 
7@ PRINT “A ROUNDED ="B 

88 GO TO 26 

9@ END 


READY 


RUNNY 

NUMBER TO BE ROUNDED? 55,65342 
NO. OF DECIMAL PLACES? 2 

A ROUNDED = 55,65 

NUMBER TO BE ROUNDEB? 78.375 
NO. OF DECIMAL PLACES? -2 

A ROUNDED = 1098 

NUMBER TO BE ROUNDED? 67.89 
NO. OF DECIMAL PLACES? -1 

A ROUNDEB = 78 

NUMBER TO BE ROUNDED? tC 


REABY 


For negative numbers, the largest integer contained in the number 
is a negative number with the same or a larger absolute value. For 
example: INT(-23)= -23, but INT(-14.39) = -15. 


NOTE 


4C in the above program terminates 
program execution. See the RSTS-l] 


System User's Guide. 


Random Number Function, RND(X) 

The random number function produces a random number between 0 and 
1. The numbers are reproducible in the same order for later checking 
of a program. The argument X in the RND(X) function call can be any 
number, as that value is ignored. 


LISTNH 

1@ REM - RANBOM NUMBER EXAMPLE 
25 PRINT “RANDOM NUMBERS” 

38 FOR I=1 TO 39 

4@ PRINT RNDB(Q), 


38 NEXT I 

68 END 

READY 

RUNNH 

RANDOM NUMBERS 
771827 78183 75174 2473969 © 781555E-1 
0283217 29159 «266449 0955597 0355541 
«412872 ©457367 283588E-1 0938025E-1 eS76575E-1 
0921722 0921417 0233682 0185255 0934515 
0259796 748138 «158665 0178746 -668 488 
0474213 828888 0785414 772491 «286224 

READY 


In order to obtain random digits from 0 to 9, change line 40 to read: 


48 PRINT INTCI@*RND(@)), 


and tell BASIC to run the program again. This time the results are: 


RUNNH 
RANBOM NUMBERS 
7 7 7 4 @ 
2 5 2 3 3 
4 4 a g a 
9 9 2 I 5 
2 7 1 | 6 
4 8 7 7 2 
READY 


It is possible to generate random numbers over any range. For exam- 
ple, if the range (A,B) is desired, use: 


(B-A) *RND (9) +A 


to produce a random number in the range A<n<B. 


Since the parameter X in RND(X) is ignored, there is an alternate 
means of calling the random number generator having no arguments: RND. 
The following line is, therefore, acceptable: 

46 PRINT RND» 
Similarly, if a number in the range (A,B) is desired, the formula: 


(B-A) *RND+A 


can be used. 


3.7.2 RANDOMIZE Statement 
The RANDOMIZE statement is written as follows: 


line number RANDOMIZE 


or, alternatively: 


Line number RANDOM 


If the random number generator is to calculate different random 
numbers every time a program is run, the RANDOMIZE statement is used. 
RANDOMIZE is placed before the first use of random numbers (the RND 
function) in the program. When executed, RANDOMIZE causes the RND 
function to choose a random starting value, so that the same program 
run twice gives different results. For this reason, it is a good 
practice to debug a program completely before inserting the RANDOMIZE 


statement. 


To demonstrate the effect of the RANDOMIZE statement on two runs 
of the same program, we insert the RANDOMIZE statement as statement 15 
in the following program: 
LISTNH 
15 RANBOMIZE 


28 FOR I=! TO 5 
25 PRINT “VALUE” I “ IS” RNBCS) 


38 NEXT I 

35 END 

READY 

RUNNH 

VALUE 1 IS .797943 
VALUE 2 IS .389979 
VALUE 3 IS .6189388 
VALUE 4 IS .132141E-1 
VALUE 5 IS .588392 
REABY 


RUNNH 


VALUE 1 IS .273@41 
VALUE 2 IS .225372 
VALUE 3. IS .894867 
VALUE 4 IS ,349851 
VALUE 5 IS 991383 
READY 


The output from each run is different. 


3.7.3 User-Defined Functions 

In some programs it may be necessary to execute the same sequence 
of statements or mathematical formulas in several different places. 
BASIC allows the programmer to define his own functions and call these 
functions in the same way he would call the square root or trig 
functions. 


These user-defined functions consist of a function name: the 
first two letters of which are FN followed by any valid variable name. 
For example: 


FNA 
FNAL 


The function is defined once at the beginning of the program be- 
fore its first use. The defining or DEF statement is formed as 
follows: 

line number DEF FNa(arguments) = <expression (arguments) > 
where a is any legal variable name. The arguments may consist of 
zero to five dummy variables. The expression, however, need not con- 
tain all the arguments and may contain other program variables not 
among the arguments. For example: 


1g DEF FNA(S) = St2 
causes a later statement: 
289 LET R = FNA(4)4+1 


to be evaluated as R=17. As another example: 


58 DEF FNBCAsB) = A+xXt2 
68 Y=FNBC14.45R3) 


causes the function to be evaluated with the current value of the 
variable X within the program. In this case the dummy argument B 
(which becomes the actual argument R3 in the function call) is unused. 
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The two following programs 


Program #1: 


LISTNH 

18 DEF FNSCA) = ATA 
20 FOR I=i TO 5 

30 PRINT I, FNSCTI) 
40 NEXT I 

5@ END 


READY 

Program $2: 
LISTNH 
19 DEF FNS(X) = XtX 
2@ FOR I=1 TO 5 
38 PRINT I, FNSCI) 
4 NEXT I 
59 END 


READY 


cause the same output: 


RUNNH 

1 1 

2 4 

3 27 

4 256 
5 3125 


READY 
The arguments in the DEF statement can be seen to have no signif- 
icance; they are strictly dummy variables. The function itself can 
be defined in the DEF statement in terms of numbers, variables, other 


functions, or mathematical expressions. For example: 


10 DEF FNACX) = X?24+3*X+4 
20 DEF FNB(X) = FNACX)/2 + FNACX) 
30 DEF FNCCX) = SORCK+4)41 


The statement in which the user-defined function appears can have 
that function combined with numbers, variables, other functions, or 


mathematical expressions. For example: 
4@ LET R = FNACX+Y+Z)*N/CYt2+D) 
A user-defined function can be a function of zero to five vari- 
ables, as shown below: 
25 DEF FNL(CXsYsZ) = SQRCKt2 + Yte + Zt2) 


A later statement in a program containing the above user-defined 
function might look like the following: 


55 LET B = FNLC(DsL»sR) 


where D, L, and R have some values in the program. 
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LISTNH 

1 ! MODULUS ARITHMETIC PROGRAM 

p) ! FIND X MOD M 

1@ DEF FNM(X,M) = X-MRINTCX/™) 
! 


20 ! FIND A+B MOD M 
25 DEF FNACA,B,M) = FNMCA+B,™) 
3843 
35 1 FIND AxB MOD M 
40 DEF FNBCA,B,™) = FNMCA*B,™) 
! 
45 PRINT 
58 PRINT “ADDITION ANB MULTIPLICATION TABLES, MOD M™ 
55 INPUT “GIVE ME AN Ms} 
6@ PRINT: PRINT “ABDITION TABLES MOD "M 
65 GOSUB 882 
78 FOR I=8 TO M-1 
75 PRINT Is" “zs 
88 FOR J=8 TO Mel 
85 PRINT FNACI,J,™)3 
98 NEXT Js PRINT: NEXT I 
168 PRINT: PRINT 
11@ PRINT "MULTIPLICATION TABLES MOD” ™ 
129 GOSUB 8868 
138 FOR I=@ TO Mel 
149 PRINT Is" "3 
158 FOR J=@ TO M-1 
169 PRINT FNB(I,J,™)3 
178 NEXT J: PRINT: NEXT I 
188 STOP 
86@ !SUBROUTINE FOLLOWS: 
819 PRINT: PRINT TABC4) 383 
820 FOR I=! TO M-1 
8358 PRINT Iss NEXT Is PRINT 
848 FOR I=1 TO 2eM+3 
853 PRINT "-"“s: NEXT Is PRINT 
868 RETURN 
878 END 


READY 


Figure 3-2 


Modulus Arithmetic 


RUNNH 


ADDITION AND MULTIPLICATION TABLES, MOD M 
GIVE ME AN M? 7 


ADDITION TABLES MOD 7 


AN BAW A 
bAN— AW 
Wheande On 


@ ood 2 6868 8 @ 
1 8 123 4 5 6 
2 @2 4 6 1 3 ~=5 
3 @ 3 6 25 1 4 
4 @ 41 5 2 6 38 
5 @ 5 3 1 6 4 2 
6 @ 6 5 43 2 1 
STOP AT LINE 188 
REaDY 


Figure 3-2 (Cont.) 


Modulus Arithmetic 


The number of arguments with which a user-defined function is 
called must agree with the number of arguments with which it is de- 


fined. For example: 


18 DEF FNA (X) = x2 + X72 
20 PRINT FNAC3s2) 


will cause an error message: 


ARGUMENTS DON*T MATCH AT LINE 268 
In a DEF statement or function reference, where a function has 


zero arguments, the function name can be written with or without 


parentheses. For example: 


10 DEF FNA = Xte 
54 #1 = FNRO) 
When calling a user-defined function, the parenthesized arguments 
can be any legal expressions. The value of each expression is sub- 


stituted for the corresponding function variable. For example: 


1% DEF FNZCX)=% 12 
eA LET A=? 
30 PRINT FNZC2+A) 


line 30 causes 16 to be printed. 


If the same function name is defined more than once, an error 
message is printed. 
16% DEF FNXC¥)=¥ 1P 


2° DEF FNYCX¥ =x +X 
ILLFG4L FN REDEFINITION AT LINF pA 


The function variable need not appear in the function expression 


as shown below: 


1@ DEF FNA (KX) = 4 +2 
ea LET R = FNAC1@)+1 
34 PRINT R 
4@ END 
RUNNH 

7 


The program in Figure 3-2 contains examples of a multi-variable 


DEF statement in lines 10, 25, and 40. 
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3.8 SUBROUTINES 

When a particular mathematical expression is evaluated several 
times throughout a program, the DEF statement enables the user to 
write that expression only once. The technique of looping allows the 
program to do a sequence of instructions a specified number of times. 
If the program should require that a sequence of instructions be ex- 
ecuted several times in the course of the program, this is also 


possible. 


A subroutine is a section of code performing some operation re- 
quired at more than one point in the program. Sometimes a compli- 
cated I/O operation for a volume of data, a mathematical evaluation 
which is too complex for a user-defined function, or any number of 


other processes may be best performed in a subroutine. 


More than one subroutine can be used in a single program, in 
which case they can Le placed one after another at the end of the 
program (in line number sequence). A useful practice is to assign 
distinctive line numbers to subroutines; for example, if the main 
program uses line numbers up to 199, use 200 and 300 as the first 


numbers of two subroutines. 


LISTNH 


1 REM - THIS PROGRAM ILLUSTRATES GOSUB AND RETURN 
18 DEF FNA(X)= ABSCINT(X)) 

28 INPUT A,B,C 

30 GOSUB 108 

48 LET A=FNACA) 

58 LET B=FNA(B) 

68 LET C=FNACC) 


72 PRINT 
8@ GOSUB 168 
98 STOP 


1@@ REM - THIS SUBROUTINE PRINTS OUT THE SOLUTIONS 

118 REM - OF THE EQUATION: AX?12 + BX +C = @ 

128 PRINT “THE EQUATION IS ” A “xXtT2 +" BAX +" C 
13@ LET D=B*B - 4xA*C 

140 IF D<>@ THEN 172 

152 PRINT “ONLY ONE SOLUTION... x "3 -B/(2*A) 

168 RETURN 

17@ IF D<@ THEN 288 

188 PRINT “TWO SOLUTIONS...X ="3 

185 PRINT (-B+SQGR(D))/(2*A): "AND X ="3 (-B-SQR(D))/(2*A) 
19@ RETURN 

2@0 PRINT “IMAGINARY SOLUTIONS... X = ("3 

205 PRINT -B/(2*A) ",” SQR(-D)/(2*A) 7) AND ("3 

287 PRINT -B/(2*A) ","3 -SQR(-D)/(2*A) 7)" 

21@ RETURN 

983 END 


READY 


RUNNH 

? by e5g7 ed 

THE EQUATION IS L*XT2 + 465 *K + -25 
TWO SOLUTIONS. ..X = ae AND X =e] 


THE EQUATION IS 1 #Xt2 + Bax + 1 
IMAGINARY SOLUTIONS... X = (2,1) AND (€ @ y-1) 
STOP AT LINE 98 


READY 


Lines 100 through 210 constitute the subroutine. The subroutine 
is executed from line 30 and again from line 80. When control returns 
to line 90 the program encounters the STOP statement and terminates 


execution. 


3.8.1 GOSUB Statement 
Subroutines are usually placed physically at the end of a program 
before DATA statements, if any, and always before the END statement. 


The program begins execution and continues until it encounters a GOSUB 
statement of the form: 

line number GOSUB <line number> 
where the line number following the word GOSUB is the first line num- 
ber of the subroutine. Control then transfers to that line in the 


subroutine. For example: 
53 GOSUB 256 


Control is transferred to line 29M in the user program. The first 


line in the subroutine can be a remark or any executable statement. 


3.8.2 RETURN Statement 
Having reached the line containing a GOSUB statement, control 


transfers to the line indicated after GOSUB; the subroutine is proc- 


essed until the computer encounters a RETURN statement of the form: 


line number RETURN 


which causes control to return to the statement following the orig- 
inal GOSUB statement. A subroutine is always exited via a RETURN 


statement. 


Before transferring to the subroutine, BASIC internally records 
the next sequential statement to be processed after the GOSUB state- 
ment; the RETURN statement is a signal to transfer control to this 
statement. In this way, no matter how many subroutines or how many 
times they are called, BASIC always knows where to go next. 
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3.8.3 Nesting Subroutines 


Subroutines can be nested: that is, one subroutine can call 
another subroutine. If the execution of a subroutine encounters a 
RETURN statement, it returns control to the line following the GOSUB 
which called that subroutine. Therefore, a subroutine can call 
another subroutine, even itself. Subroutines can be entered at any 
point and can have more than one RETURN statement. It is possible 
to transfer to the beginning or any part of a subroutine; multiple 
entry points and RETURNs make a subroutine more versatile. 


The maximum level of GOSUB nesting is dependent on the size of 
the user program and the amount of core storage available at the 


installation. Exceeding this limit results in the message: 


MAXIMUM CORE SIZE EXCEEDED AT LINE xxx 


where xxx is the line number of the line containing the error. 


3.9 STOP AND END STATEMENTS 

The STOP and END statements are used to terminate program execu- 
tion. The END statement is the last statement in a BASIC program. 
The STOP statement can occur several times throughout a single pro- 
gram with conditional jumps determining the actual end of the program. 


The END statement is of the form: 
line number END 


The line number of the END statement should be the largest line num- 
ber in the program, since any lines having line numbers greater than 
that of the END statement are not executed and are not retrieved 


by the OLD command (although they are saved with the SAVE command). 


NOTE 


A program will execute without an END statement; 
however, an error message is printed if a pro- 
gram is recalled having been saved without an 
END statement. 

The STOP statement is of the form: 


line number STOP 
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and causes: 


STOP AT LINE line number 
READY 


to be printed when executed. A CONTINUE command entered at this point 
resumes execution at the statement following STOP. 


Execution of a STOP or END statement causes the message: 
READY 
to be printed by the teleprinter. This signals that the execution of 


a program has been terminated or completed, and BASIC is able to ac- 
cept further input. 
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PART II 


BASIC-PLUS ADVANCED FEATURES 


This part of the manual describes the special features of BASIC- 
PLUS which make the language a superior tool for all manner of data 
manipulation. Additional capabilities of the statements previously 
described are included, along with new statements, character string 
manipulating facilities, integer mode variables and arithmetic, and 
intrinsic matrix functions. Also described is the immediate mode of 


operation which causes BASIC to treat single statements as commands. 


In general, the new techniques presented here allow the user to 
write programs which conserve core space and reduce execution time. 
With the ability to manipulate character strings, the user can write 


sophisticated programs to handle a wide range of data. 
The matrix functions allow the user to perform matrix I/O and 


the matrix operations of addition, subtraction, multiplication, 


inversion and transposition. 


It 


CHAPTER 4 


IMMEDIATE MODE OPERATIONS 


4.1 USE OF IMMEDIATE MODE FOR STATEMENT EXECUTION 

It is not necessary to write a complete program to use BASIC-PLUS. 
Most of the statements discussed in this manual can either be included 
in a program for later execution or be given on-line as commands, which 
are immediately executed by the BASIC processor. This latter facility 
permits the RSTS-11 user to have an extremely powerful desk calculator 


available whenever he is on-line. 


BASIC-PLUS distinguishes between lines entered for later execution 
and those entered for immediate execution solely on the presence (or 
absence) of a line number. Statements which begin with line numbers 
are stored; statements without line numbers are executed immediately 


upon being entered to the system. Thus the line; 
10 PFINT "THIS 1S A PDR-}I" 


produces no action at the console upon entry, while the statement: 


PEINT "THIS IS A fFnr-11" 
THIS IS A PDP-11 


KEADY 


when entered causes the immediate output shown above. The READY mes- 
sage is then printed to indicate the system readiness for further in- 


put. 


4.2 PROGRAM DEBUGGING 

Immediate mode operation is especially useful in two areas: pro- 
gram debugging and the performance of simple calculations in situations 
which do not occur with sufficient frequency or with sufficient com- 


plications to justify writing a program. 


In order to facilitate debugging a program, the user can 
place STOP statements liberally throughout the program. Each STOP 
statement causes the program to halt, printing the line number at which 
the STOP occurred; at which time the user can examine various data 


values, perhaps change them in immediate mode, and then give the 


CONT 


command to continue program execution. However, a syntax error in 
immediate mode or one of several other conditions could prevent 


continuation of program execution with the CONT command. 


When using immediate mode, nearly all the standard statements 


can be used to generate or print results. 


The user can also halt program execution at any time by typing 
CTRL/C. Immediate mode can then be used to examine and/or change 
data values. Typing the CONT command resumes program execution. 


Whenever execution cannot be continued, the message: 
CAN'T CONTINUE 
FFALDY 


is printed upon entering the CONT command. 
4.3 MULTIPLE STATEMENTS PER LINE 


Multiple statements cannot be used on a single line in immediate 


mode. For example: 


A=l: PRINT A 
ILLEGAL IN IMMEDIATE MODE 


READY 


The use of the FOR modifier (and all other modifiers described 
in Section 8.7) is allowed. Thus a table of square roots can be 


produced as follows: 


PRINT I, SQR(1) FOR I=! To 18 
. 1 

1.41421 

1.73285 

2 


2.235687 
2.44949 
2.64575 
2.82843 
3 

8 3.16228 


—ONQADUN RUD — 


READY 


4.4 RESTRICTIONS ON IMMEDIATE MODE 
Some statements, particularly those that would cause execution of 
lines within a user's stored program, are not allowed in immediate 


mode. These statements include: 


GOTO 
GOSUB 
References to user-defined functions 


Thus the following dialog might result if the user defined a function 


in his program and tried to reference it in immediate mode. 


10 DEF FNACX) = Xt2 + 2eX ISAVED STATEMENT 
PRINT FNACI) {IMMEDIATE MODE 


PLEASE USE THE RUN COMMAND 
READY 


Certain commands make no logical sense when used in immediate mode. 


Commands in this category include: 


DEF 
DIM 
DATA 
FOR 
RETURN 
NEXT 
FNEND 


When any of these are given, the message ILLEGAL IN IMMEDIATE MODE is 


printed: 


DEF FNXCY)=1 
ILLEGAL IN IMMEDIATE MODE 


READY 


5.1 CHARACTER STRINGS 


CHAPTER 5 


CHARACTER STRINGS 


The previous chapters describe the manipulation of numerical in- 


formation; however, BASIC also processes information in the form of 


character strings. 


ters treated as a unit. 


A string, in this context, is a seguence of charac- 


A string can be composed of any combination 


of the characters in Table 5-2. 


Without realizing it, the reader has already encountered character 


strings. 


month, given its number: 


LISTNH 


10 
15 
2g 
a5 
3h 
35 
AG 
45 
59 
$5 
69 
65 
79 
7S 
88 
85 


INPUT 


IF 
IF 
IF 
IF 
IF 
IF 


TE 2 


IF 
IF 
IF 
IF 
IF 
IF 
IF 


END 


READY 


RUNNH 


TYPE | 
THE 


9 


READY 


N<1 
N>3 
N=] 
N=2 
N=3 
Ne4 


N=Q 


N=19 
Nett 


THEN PRINT 
THEN PRINT 


Consider the following program which prints the name of a 


"TYPE A NUMREP RETWEEN 1 AND 1e8"3 4 

OF N>12 THEN PRINT "NUMBER OUT OF RANGE" su0TU 19 
THEN PRINT “THE N “TH MONTH IS "3 

THEN PHINT "THE FIRST MONTH IS JANUARY" 
THEN PRINT "THE SECOND MUNTH IS FemriIary' 
THEN PRINT "THE THIRD MONTH IS MARCH" 
THEN PRINT "APRIL" 

THEN PRINT "MAY" 

THEN PRINT "SINE" 

THEN PRINT "JULY" 

THEN PHINT "AUGUST" 

THEN PRINT "SEPTEMBEI 


"OCTOBER" 
"NOVEMBER" 


N=1le THEN PRINT "DECEMBER" 


NUMRER BETWEEN 1 AND 127 9 
TH MONTH IS SEPTEMBER 


In Chapter 3 the INPUT and PRINT statements were shown printing 
messages along with the input and output of numeric values (see lines 
10 and 15 above). These messages consist of character string constants 
(just as 4 is a numeric constant). In a similar way, there are char- 


acter string variables and functions. 


5.1.1 String Constants 


Just as numbers can be used as constants or referenced by vari- 
able names, BASIC-PLUS allows for character string constants. Charac- 
ter string constants are delimited by either single or double quotes. 


For example: 


195 LET YS = "FILE4" 
33. B1S = 'CAN' 
86 IF AS = "YES" GOTO 259 


where "FILE4", 'CAN' and "YES" are character string constants. 


5.1.2 Character String Variables 


Variable names can be introduced for simple strings and for both 
lists and matrices composed of strings (which is to say one and two 
dimensional string matrices). Any legal name followed by a dollar 


sign ($) character is a legal name for a string variable. For example: 


AS 
C7$ 


are simple string variables. Any list or matrix variable name fol- 
lowed by the $ character denotes the string form of that variable. 


For example: 


VS (N) M2$ (N) 
C$ (M,N) G1$ (M,N) 


(where M and N indicate the position of that element of the matrix 


within the whole) are list and matrix string variables. 


The same name can be used as a numeric variable and as a string 
Variable in the same program with the restriction that a one anda 
two dimensional matrix cannot have the same name in the same program. 


For example: 


A A(N) 
AS A$ (M,N) 


can ail be used in the same program, but 
A(N) and A(M,N) 

cannot. Likewise, 
AS(N) and AS (M,N) 

cannot both occur in the same program. 


Just as numeric variables are automatically initialized to # when a 
program is run, string variables are initialized to a null string 


containing zero characters (the character string constant ""). 


5.1.3  Subscripted String Variables 


String lists and matrices are defined with the DIM statement, as 


are numerical lists and matrices. For example: 
19 DIM S13C5) 


indicates the S1$ is a string matrix with six elements, $1$(#) through 
S1$(5), which can be separately accessed. If a DIM statement is not 
used, a subscripted string variable is assumed to have a dimension of 
10 (11 elements including the zero element) in each direction. Note 
that the dimension of a string matrix specifies the number of strings 
and not the number of characters in any one string. For example, if 
the first statements in a program are: 


19 FOR IT=1 TO 7 
23 LET RSCT)="PEPp-211" 
34 NEXT I 


they would cause a list B$(n) to be created having 11 accessible ele- 
ments, B$(f) through B$(1f). The elements B$(1) through B$(7) are set 
equal to "PDP-11" and the others would be null strings (have no char- 
acters). As a general rule, all lists and matrices should be dimen- 


sioned to the maximum size being referenced in the program. 


5.1.4 String Size 


A character string can contain any number of characters limited 
only by the amount of core storage available. However, the 
LINE FEED key cannot be used to type a string on two or more terminal 
lines. Since core storage is limited, strings can also be saved in 
files on the system disk (see Section 9.6.2). 


5.1.5 Relational Operators 
When applied to string operands, the relational operators indi- 


cate alphabetic sequence. For example: 
55 IF ABCI) < ABCI+1) GOTO 198 


When line 55 is executed the following occurs: A$(I) and AS(I+1) are 
compared; if A$(I) occurs earlier in alphabetical order than A$(I+l), 
execution continues at line 100. Table 5-1 contains a list of the 


relational operators and their string interpretations. 


Table 5-1 


Relational Operators Used With 
String Variables 


Operator Meaning 


The strings A$ and B$ are equivalent. 


The string A$ occurs before B$ in alpha- 
betical sequence. 


The string A$ is equivalent to or occurs 
before B$ in alphabetical sequence. 


The string A$ occurs after B$ in alpha- 
betical sequence. 


The string A$ is equivalent to or occurs 
after B$ in alphabetical sequence. 


The strings A$ and B$ are not equivalent. 


In any string comparison, trailing blanks are ignored. That is to 
say "YES" is equivalent to "YES ". Where two strings of unequal length 
are compared, the shorter is padded with trailing blanks to the length of 
the longer string. A null string (of length zero) is considered to be 
completely blank and is less than any string of length greater than zero 
unless that string consists of all blanks in which case the two strings 


are equal. 


5.2 ASCII STRING CONVERSIONS, CHANGE STATEMENT 

Individual characters in a string can be referenced through use 
of the CHANGE statement. The CHANGE statement permits the user pro- 
gram to transform (the entirety of) a character string into a list of 
numeric values or a list of numeric values into a character string. 
Each character in a string can be converted to its ASCII equivalent 
or vice versa. Table 5-2 describes the relationship between the ASCII 


characters and their numerical values. 


As an illustration, consider the following: 


LISTNH 

1@ DIM X(3) 

15 LET A$ = "CAT" 
2@ CHANGE A$ TO x 


25 PRINT XB) 3X C1) 3X (2) 3X (3) 
3@ END 


READY 


RUNNH 
3 67 65 84 


READY 


X(1) through X(3) take on the ASCII values of the characters in the 
string variable A$. The first element of X, X(f), becomes the number 
of characters present in A$. If more characters are present in the 
string variable than can be accommodated in the numeric list, the 
message "SUBSCRIPT OUT OF RANGE" is printed. The first element of 
the list becomes the number of characters in the string which have 
been successfully transformed into numeric values, and will be less 
than or equal to the dimension of the list. 


Table 5-2 


ASCII Character Codes 


ASCII ASCII ASCII 
Decimal Char- RSTS Decimal Char- RSTS Decimal Char- RSTS 
acter Value acter Usage Value acter Usage 


g FILL character Vv 
1 SOH 87 Ww 
2 STX 88 x 
3 ETX CTRL/C « 89 Y 
4 EOT / 98 Zz 
5 ENQ g 91 [ 
6 ACK 1 92 \ 
7 BEL BELL 2 93 J 
8 BS 3 94 “or + 
9 HT HORIZONTAL TAB 4 95 — or + 
1¢ LF LINE FEED 53 5 96 “ Grave accent 
11 VT VERTICAL TAB 54 6 97 a 
12 FF FORM FEED 55 7 98 b 
CARRIAGE RETURN 56 8 99 c 
57 9 19g a 
CTRL/O 3 191 e 
; 1g2 £ 
< 193 g 
= 194 h 
> 195 i 
? 196 j 
@ 197 k 
A 198 1 
B 199 m 
Cc 11¢ n 
D 111 ° 
CTRL/Z 69 E 112 p 
ESCAPE? 76 F 113 q 
71 G 114 xr 
72 H 115 s 
73 I 116 t 
74 J 117 u 
75 K 118 Vv 
76 L 119 w 
77 M 129 x 
78 N 121 y 
719 oO 122 Zz 
7] P 123 { 
81 Q 124 | Vertical Line 
82 R 125 } 
83 s 126 ~ Tilde 
84 T DEL RUBOUT 
42 85 U 
: JALTMODE (ASCII 125) or PREFIX (ASCII 126) keys which appear on some terminals are 
translated internally into ESCAPE. 


NOTE 


The decimal values 128 through 255 can appear in character strings. For most 
practical purposes, the characters represented by N and N+128 (decimal) are the 
same. However, the characters CHR$(N) and CHR$(N+128) do not test as equal if com- 
pared. Users should be careful when performing output of these values since they may 
have some significance in certain device-dependent operations (see Chapter 12). 
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Another program which transforms a character string into a list 


of numeric values is shown below: 


LISTNH 
1f@ DIM AC65) 
15 READ A$ 


2@ CHANGE A$ TO A 

25 FOR I=8 TO ACB) 

32 PRINT ACI) $3eNEXT I 

35 DATA ABCDEFGHI JKLMNOPQRSTUVWXYZ 
4@ END 


READY 


RUNNH 

26 65 66 67 68 69 78 71 72 73 74 #75 #76 #77 #%78 %79 8B 
82 83 84 85 86 87 88 89 98 

READY 


Notice that A(#) = 26. 


To change numbers into string characters, CHANGE is used as 
follows: 


LISTNH 

1@ FOR 1=8 To 5 

15 READ ACI) 

20 NEXT I 

25 DATA 5,65,66,67,68,69 
30 CHANGE A TO ag 


35 PRIN 
PRINT AS 


READY 


RUNNH 
ABCDE 


READY 


This program prints ABCDE because the numbers 65 through 69 are 
the code numbers for A through E. 


Before CHANGE is used in the matrix-to-string direction, the pro- 
grammer must indicate the number of characters in the string as the 
zero element of the matrix. In line 15 of the previous program, A(§) 
is read as 5. The following is another example of a numeric list to 


character string conversion: 


LISTNH 

16 DIM VC128) 

15 INPUT "HOW MANY CHARACTERS” 3V(@) 
2@ FOR I=1 TO V¢@) 

25 INPUT V(I) 

30 NEXT I 

35 CHANGE V TO A$ 

42 PRINT A$ 

5@ END 


READY 


RUNNH 
HOW MANY CHARACTERS? 3 
? 67 
? 64 
? 87 


cew 


READY 
Numbers which have no character equivalent in Table 5-2 do not 


cause a character to be printed. 


5.3 STRING INPUT 
The READ, DATA and INPUT statements can be used to input string 


variables to a program. For example: 


18 READ A$, B, C, D 
2@ DATA 17, 14, 13.4, CAT 


causes the following assignments to be made: 


AS = the character string "17" 
B = 14 
c = 13.4 


reading D as CAT causes the message ILLEGAL NUMBER AT LINE 19 
to be printed. 

Quotation marks are necessary around string items in DATA state- 
ments only if the string contains a comma or if leading, trailing or 
embedded blanks within the string are significant. Quotes (single or 
double) are always acceptable around string items, even though not 
always necessary. For example, the items in line 40 in the following 
program are all acceptable character strings and would be read as 


printed. 
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LISTNH 

18 READ A$,B$,C$,D$,E$ 

26 PRINT A$sB$3C$sD$sE$ 

38 PRINT A$,BS,C$,D$,E$ 

42 DATA “MR. JONES",MISS SMITH, “MRS. BROWN", "MISS", ""MR™’ 


READY 

RUNNH 

MRe JONESMISSSMITHMRS, BROWNMISS™" MR” 

MR. JONES MISSSMITH MRS. BROWN MISS "MR" 
READY 


A READ statement can appear anywhere in a multiple statement line, 

but a DATA statement must be the last statement on a line. See also 
the MAT READ statement which reads matrices (either numeric or string), 
Section 7.2. 


NOTE 


The data pool composed of values from the 
programmed DATA statements is stored in- 
ternally as an ASCII string list. Where 

a numeric variable is read, the appropriate 
ASCII to numeric conversions are performed. 
Where a string variable is read, the string 
is used as it appears in the DATA statement. 
If the item did not appear in quotes, lead- 
ing, trailing and embedded spaces are ig- 
nored. If the item did appear in quotes, 
the string variable is equated to the en- 
tire string within the quotes. 


The INPUT statement is used to input character strings exactly 
as though accepting numeric values. For example: 


14 INPUT "YOUR NAME" SNSs"YOUR AGE"SA 


is functionally equivalent to: 


34 PRINT “YOUR NAMEN; 
35 INPUT NS 

44 PRINT “YOUR AGE'"3 
45 INPUT A 


Another feature of the INPUT statement when used with character 
string input is the INPUT LINE statement of the form: 


tine number INPUT LINE <string variable> 


For example: 
19 INPUT LINE AS 


which causes the program to accept a line of input from the terminal 
with embedded spaces, punctuation characters, or quotes. Any characters 
are acceptable in a line being input to the program in this manner. 

The program can then treat the line as a whole or in smaller segments 


as explained in Section 5.5 which describes string functions. 


No text string can be output with the INPUT LINE statement, this 
facility is only available in the INPUT statement. For example: 


10 INPUT LINE “TEXT"3A$ 
SYNTAX FRROR AT LINE 16 


An INPUT LINE statement reads the entire line as typed by the 
user, including the line terminating character. The line terminator 
is one of the following: 

a. Carriage return/line feed, generated by typing 


the RETURN key (appends the ASCII values 13 and 
18 to the character string); 


b. Line feed, generated by typing the LINE FEED 
key (appends the ASCII values 1, 13 and 8 to 
the character string): or 


c. ESCAPE, generated by typing the ESCAPE, ALT MODE 
or PREFIX key, depending upon the terminal (ap- 
pends an ASCII 27 to the character string). 


5.4 STRING OUTPUT 
When character string constants are included in PRINT statements, 
only those characters within quotes are printed. No leading or trail- 


ing spaces are added. For example: 


LISTNH 

10 X=1-e92Y=2.91:AS="A=" 
20 PRINT AS3X" Betty 

39 PRINT "DONE" 

44 END 


READY 


RUNNH 
A= 1 BF 24@1 
DONE 


READY 


Semicolons separating character string constants from other list items 
are optional. For example, in line 20 (above) note that the variable Y 


is not separated from the character string " B=" by a semicolon. 


Character string output can also contain the string functions de- 


scribed in Section 5.5. 


5.5 STRING FUNCTIONS 


Like the intrinsic mathematical functions {(e.g., SIN, LOG), BASIC- 
PLUS contains various functions for use with character strings. These 
functions allow the program to concatenate two strings, access part of 
a string, determine the number of characters in a string, generate a 
character string corresponding to a given number or vice versa, search 
for a substring within a larger string, and perform other useful opera- 
tions. (These functions are particularly useful when dealing with whole 
lines of alphanumeric information input by an INPUT LINE statement.) 
The various functions available are summarized in Table 5-3. 


5.5.1 User-Defined String Functions 


Character string functions can be written in the same way as 
numeric functions. (See Section 3.7.3 and 8.1.) The function is in- 
dicated as being a string function by the $ character after the func- 


tion name. 


User-defined string functions return character string values, al- 
though both numeric and string values can be used as arguments to the 
function. For example, the following multiple-line function (see 
Section 8.1) returns the string which comes first in alphabetical or- 


der: 


19 DEF FNFS$(AS5sBS) 

2a FNFS=AS 

34 IF AS>BS THEN FNFS=R$ 
49 FNEND 


The following function combines two strings into one string: 


10 DEF FNCSC(XS$s7Y$)=X$+Y$ 


Numbers cannot be used as arguments in a function where strings 


are expected or vice versa. Line 80 is unacceptable: 


19 DEF FNASCAG) = CHRSCLENCA$)+4+1) 
80 LET Z=FNASC4) 


The message: 


ARGUMENTS DON'T MATCH AT LINE &4% 


is printed. 


The following code is a string function which returns the leftmost 


five characters from the sum of three arguments: 


LISTNH 

75 DEF FNASCXsYsZ7) = LEFTCNUMSCX+Y+Z)55) 
8A PRINT FNAS(C14952%53) 

READY 


RUNNH 
123 


READY 


NUMS$ (123) is a five-character string, as follows: 


" (space) 123 (space) " 


Function Code 


LEFT (A$ ,N%) 


RIGHT (AS ,N%) 


MID (AS$,N1% ,N2%) 


LEN (A$) 


CHRS (N&) 


ASCII (AS) 


DATES (N%) 


Table 5-3 
String Functions? 


Meaning 


Indicates a substring of the string AS from the first 
character through the Nth character (the leftmost N 
Characters of the string A$). For example: 


PRINT LEFT(A$37%) 

ABCDEFG 
Indicates a substring of the string AS from the yth 
character through the last character in A$ (the right- 
most characters of the string A$ starting with the 
nth character). For example: 


PRINT RIGHT(ASs2q0%) 
TUVWXYZ 


Indicates a substring of the string A$ starting with 
character Nl, and N2 characters long (the characters 
between and including the Nl through N1+N2-1 characters 
of the string AS). For example: 


PRINT MIDCA$515%552) 
OPARS 


Indicates the number of characters in the string A$ 
(including trailing blanks). For example: 


PRINT LENCAS) 
26 


Indicates a concatenation operation on two strings. 
For example "ABC"+"DEF" is equivalent to "ABCDEF",. 
"12"+"34"4"56" is equivalent to "123456". 


Generates a one-character string having the ASCII 
value of N (see Table 5-2). For example: CHRS(65) is 
equivalent to "A". Only one character can be generated. 


Generates the ASCII value of the first character in 
A$. For example, ASCII("X") is equivalent to 88, the 
ASCII equivalent of X. If BS = "XAB", then ASCII(BS) 
= 88. 


where N=f, this function returns the current date in 
the form: 
12-Aug-72 


This quantity can be printed on output by simple ref- 
erence to the function. It should be noted that dates 
are output using both upper and lower case letters, 
i.e., Jan, Feb, Mar, etc. where the output device is 
capable of generating lower case letters. Where N#f, 
the function translates N into a date string. (See 
Section 8.8.) 


‘AS in the immediate mode examples is assumed to be 
“ABCDEFGHIJKLMNOPQRSTUVWXYZ". 


Table 5-3 


String Functions (continued) 


Function Code 


INSTR(N13%,AS$,BS) Indicates a search for the substring BS within the 
string AS beginning at character position Nl. Re- 
turns a value of @ if BS is not in A$, and the char- 
acter position if BS is found to be in AS (character 
position is measured from the start of the string wit 
the first character counted as character 1). For 
example: : seh bony are 

PRINT INST? C54sAbs"0P") 
15 


SPACES (N$%) Indicates a string of N spaces, used to insert 
spaces within a character string. 


NUMS (N) Indicates a string of numeric characters represent- 
ing the value of N as it would be output by a PRINT 
statement. NUMS$(n)=(space)n(space) if n>g and 
NUMS (n)=-n(space) if n<f. For example: 


PRINT NUMSC1.20) "A" 
1A 


VAL (AS) Computes the numeric value of the string of numeric 
characters AS (may include digits, +, -, . and E). 
If AS contains any characters not acceptable as 
numeric input with the INPUT statement, an error 
results. For example: 


PRINT VALC'1 SEIN) 
15 
TIMES (N) Where N=, this function returns the current time- 
of-day as a string of the form: 
1:38 PM 


where N#f#, the function translates N into a time 
string (see Section 8.8). 


CHAPTER 6 


INTEGER VARIABLES AND INTEGER ARITHMETIC 


6.1 INTEGER CONSTANTS AND VARIABLES 


Normally, all numeric values (variables and constants) specified 
in a BASIC program are stored internally as floating-point numbers. 
If operations to be performed deal with integer numbers, Significant 
economies in storage space can be achieved by use of the integer 
data type (which uses only one computer word per value). Integer 
arithmetic is also significantly faster than floating-point arith- 
metic. Integer variables (and constants) can assume values in the 
range -32768 to +32767. 


A constant, variable, or function can be specified as an inte- 
ger by terminating its name with the % character. For example: 
100% A% FNX$% (Y) 
-4% Al1% FNL$ (N%,L%) 
The user is expected to indicate where an integer constant is to be 
generated by using the % character. Otherwise a floating-point value 
is normally produced. 


When a floating-point value is assigned to an integer variable, 
the fractional portion of that number is lost. The number is not 
rounded to the nearest integer value. (A FIX function is performed 
rather than an INT function.) For example: 


causes A% to be assigned the value -1. 
6.2 INTEGER ARITHMETIC 


Arithmetic performed with integer variables is performed modulo 
2+15. The number range -32,768 to +32,767 is treated as continuous, 
with the number after +32,767 equal to -32,768. Thus, 32767% + 2% = 
~32767% and so on. 


Integer division forces truncation of any remainder; for example 
5%/7%=0 and 199%/100%=1. Operations can be performed in which both 
integer and floating-point data are freely mixed. The result is stored 
in the format indicated as the resulting variable, for example: 


25 LET X&2 = NZ + FNACR)*2 


The result of the expression on the right is truncated to provide an 


integer value for X%. 


Arithmetic is performed in integer mode only when an explicit 
integer term appears in the statement to the left of an operator and 
no floating-point term appears to the right. Thus, for example: 


PHINT 22/4 
a 


prints a @ (since 4 is expressed as an integer), but 


PHINT 22/4. 
5 


prints .5 (since 4. is stored internally as a floating-point number). 


Where program size is critical, the use of the % character to 
generate integer values is encouraged as it uses significantly less 


storage space. For example: 
19 FOR I4=12% TO 142 
takes less storage space and executes faster than: 


19 FOR I=i TO 14 


6.3 INTEGER 1/0 


Input and output of integer variables is performed in exactly 
the same manner as operations on floating-point variables. (Remember 
that in cases where a floating-point variable has an integer value it 
is automatically printed as an integer but is still stored internally 
as a floating-point number and hence takes more storage space.) It is 
illegal to provide a floating-point value for an integer variable 
through either a READ or INPUT statement. For example: 


LISTNH 

18 READ A, BZ, C, D2, E 

2@ PRINT A, BZ, C, DZ, E 
3D DATA 22743545507, 608 

READY 

RUNNY 


ILLEGAL NUMBER AT LINE 198 
READY 


when line 39 is changed to 
BD DATA 2079594595608 
the following is printed: 
RUNNH 
2.7 3 4 5 6.8 


READY 


6.4 USER DEFINED INTEGER FUNCTIONS 


Functions can be written to handle integer variables as well as 
floating-point variables (see Sections 3.7.3 and 8.1). A function is 
defined to be of integer type by following the function name with the 


% character. 


A function to return the remainder when one integer is divided 


by another is shown below: 


16 DEF FNRACIZ,JZ) = 18-23% * CIR JZ) 


and could be called later in a program as follows: 


100 PRINT FNRZCAZ5112%) 


Integer arguments can be used where floating-point arguments are 
expected and vice versa as the system performs the necessary conver- 
sions. However, strings cannot be used where numbers are required (or 


vice versa). 


7S DEF FNAZCXZ) =XZ-1% 
86 LET Z2=FNA%Z(12¢34) 


is acceptable. 2Z equals 11 after line 80 has been executed. 


6.5 USE OF INTEGERS AS LOGICAL VARIABLES 


Integer variables or integer valued expressions can be used within 
IF statements in any place that a logical expression can appear. An 
integer value of $% corresponds to the logical value FALSE, and any 
non-zero value is defined to be TRUE. The logical operators (AND, OR, 
NOT, XOR, IMP, EQV) operate on logical data in a bitwise manner. For 
example, (X% AND Y%) could be used to mask a particular bit pattern in 
Y%. The integer -1% (which is represented internally as sixteen binary 
ones) is normally used by the system when a TRUE value is required. 


Logical values generated by BASIC always have the values -1% (TRUE) 
and @% (FALSE). 


The following Immediate Mode sequence illustrates the use of in- 


tegers in logical applications: 


IF -1% THEN PRINT “TRUE” ELSE PRINT “FALSE” 
TRUE 


READY 


IF -12 AND 02 THEN PRINT “TRUE” ELSE PRINT “FALSE” 
FALSE 


READY 


IF 42 AND 2% THEN PRINT “TRUE” ELSE PRINT “FALSE” 
FALSE 


READY 


TF -12 IMP -1% THEN PRINT “ TRUE" ELSE PRINT "FALSE" 
TRUE 


READY 


IF 1<@ XOR -12 THEN PRINT “TRUE” ELSE PRINT “FALSE” 
TRUE 


READY 


If the LET statements in lines 3f and 49 were moved to some other line 
numbers, lines 11f and 12% would also require a change. 


8.5 IF-THEN-ELSE STATEMENT 


The IF-THEN statement allows the program to transfer control to 
another line or execute a specified statement depending upon a stated 


condition. 


The IF-THEN-ELSE statement is the same as the IF-THEN statement, 
except that rather than executing the line following the IF statement, 
another line number or statement can be specified for execution where 
the condition is not met. The statement is of the form: 


ELSE< Line number>y 


THEN<line number> 
ELSE< statement> 


Line number IF<conditton> THEN<statement> 
GOTO<line number» 


where the condition is defined as one of the following: 

<relational expresston> <logical operator> <relattonal expresston> 
and a relational expression is defined as: 

<expresston> <relational operator> <expresston> 


as described in Section 3.5. The relational condition is tested; if 
it is true the THEN/GOTO part of the statement is executed. If the 
condition is false, the ELSE part of the statement is executed. Fol- 
lowing the word ELSE is either a statement to be executed or a line 
number to which control is transferred. 


As an example of an IF-THEN-ELSE statement: 
45 Ik X>Y THEN PRINT "GREOATFR" BLOF FRIVT "VOT GEFATFR" 


An IF statement can follow either the THEN or ELSE clause in the above 


statement, making it possible to nest IF statement to any desired level. 
For example: 


109 IF A>F THEN IF R>C THEN PRIVY "A>R>Ct 


CHAPTER 7 


MATRIX MANIPULATION 


This Chapter deals with BASIC-PLUS matrix manipulation commands. Ma- 
trices can be composed of variables of any type. A single matrix, how- 
ever, is composed of a single type of data: floating-point, integer, 
or character string. The MAT operations do not set the zero elements 
[A(#), or B(#,n) and B(n,f)] of the specified matrix to conform with 
the requested operation. 


7.1 BASIC-PLUS ARRAY STORAGE 


A BASIC-PLUS program can define the size of a matrix in one of 
two ways: explicitly, by including the matrix in a dimension state- 
ment, or implicitly, where the matrix does not appear in any dimension 
statement. Implicitly dimensioned matrices are assumed to have ten 
elements in each dimension referenced (size 10 for a one-dimensional 
matrix and size 10 by 10 for a two-dimensional matrix, with each 
dimension also having a zero row and column). Implicitly dimensioning 
the matrix A(I,J), for example, has the same effect as explicitly in- 


cluding the following statement: 
19 DIM AC1%s14) 


Dimensioning a matrix (explicitly or implicitly) establishes two 
quantities for the system: the default number of elements in each 
row and column and the maximum number of elements in the matrix. 
Through use of the MAT commands, described in this Chapter, the program 
can alter the number of elements in each row and the number of columns 
in the matrix as long as the total number of elements does not exceed 
the number defined when the matrix was dimensioned. Changing the num- 
ber of elements in either or both dimensions is termed redimensioning 
the matrix. 


When a matrix is redimensioned, the user program should take 
care not to reference elements outside the currently dimensioned 
range of the matrix. For example, if the range of matrix A is 5 by 7, 
referencing A(3,8) is improper and, although no error is generated, 
generally results in some element elsewhere in the matrix being 


destroyed. 


7.2 MAT READ STATEMENT 


The MAT READ statement is used to read the value of each element 
of a matrix from DATA statements. The format of the statement is as 


follows: 
line number MAT READ <itst of matrtces> 


Each element in the list of matrices indicates the maximum amount of 
the matrix to be read (which cannot be greater than the dimensioned 
size of the matrix). The individual elements are separated by commas. 
If the matrix name is used without a subscript, the entire matrix is 


read. For example: 


16 DIM ACA4,2M) 

Pa MAT READ A 
The above lines read a twenty by twenty matrix of floating-point data. 
Data is read row by row; that is, the second subscript varies most 


rapidly. If line 20 had read: 


aa VAT READ AC5s15) 


a five by fifteen matrix would be read and the matrix A would be re- 


dimensioned. 


7.3. MAT PRINT STATEMENT 


The MAT PRINT statement prints each element of a one or two 


dimensional matrix. The statement is of the form: 
line number MAT PRINT <matrix name> Lad 


If the matrix name consists of an unsubscripted matrix name, the 
entire matrix is printed. If the matrix name is subscripted, then 
the subscript indicates the maximum size of the matrix to be printed 
(but does not redimension the matrix). Only one matrix can be out- 
put by a single MAT PRINT statement. 


If the matrix name is followed by a semicolon (;), the data 
values are printed in a packed fashion. If the matrix name is 
followed by a comma (,), the data values are printed across the 


line with one value per print zone. If neither character follows 


the matrix name (the null case), each element is printed on a 


separate line. 


14 DIM AC14s19)5B(0295200) 


129 MAT PRINT A3 fPRINT 194*14 MATRIXsPACKED FORMAT 
134 MAT PRINT BCNsM)» IPRINT N*M MATRIXs 5S ELEMENTS 
tpEP LINE 


One dimensional arrays can be printed in either row or column 
format. 


MAT PRINT V 


where V is a singly dimensioned array, prints the array V as a 
column matrix, and 


MAT PRINT Vs 
prints the array V as a row matrix, five values per line. 
MAT PRINT V3 


prints the array V as a row matrix, closely packed. For example: 


LISTNH 

10 DIM AC7)5xXC5) 

29 MAT READ Ask 

343 MAT PRINT ASSPRINT:MAT PRINT X 

49 DATA 21522 5235245355 36537951 352953954955 
54 EN) 


READY 


RUNNY 

21 22 23 84 35 36 37 
‘Sl 

52 

53 

54 

55 


7.4 MAT INPUT STATEMENT 


The MAT INPUT statement is used to input the value of each 


element of a predimensioned matrix. The statement is of the form: 


line number MAT INPUT <itst of matrices> 


Input is read from the keyboard, as with a normal INPUT statement, 


and a ? character is printed when the program is ready to accept the 


input. The LINE FEED key can be used to continue typing data on suc- 
ceeding lines. The RETURN or ESCAPE key is used to enter the data to 
the system. MAT INPUT does not affect row zero or column zero of the 


matrix. 


The MAT INPUT statement allows input of integer, floating-point 
or character string values depending upon the variable names. Where 
more than one matrix is to be input by the same MAT INPUT statements, 


the names are separated by commas. For example: 


19 DIM AZ¢C2A)sRO15) 
29 MAT INPUT A&zsR 


causes the program to input twenty integer elements for the array 
A% and fifteen floating-point values for the array B. 


Where an array or matrix element is specified, for example: 
249 MAT INPUT NZ¢25) 


only 25 elements of the array are input, regardless of the number of 
elements originally specified when the array was dimensioned. The 


array is then redimensioned. For example: 


59 DIM AC24525)2B2C822) 


199 MAT INPUT AC28s51) 
119 MAT INPUT B4ZsCS 


The matrix A is redimensioned in line 1%. The INPUT statement pro- 
ceeds to accept input until the entire matrix has been read or the 
RETURN or ESCAPE delimiter is encountered. Several lines can be 
input by terminating the physical keyboard line with a line feed to 


indicate continuation on the following line. 


Following the input of a matrix, the two variables NUM and NUM2 
contain the number of elements input. NUM contains the number of 
elements entered in the last row, and NUM2 contains the number of 
rows input. For example, the following program inputs a variable 


size matrix (up to 1@*19): 
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53 DIM AC10s1@) 

149 INPUT “TYPE MATRIX DIMENSIONS"3NsoM 

116 MAT INPUT ACNs™) 

120 !CHECK TO SEE IF ENTIRE MATRIX WAS ENTERED 
139 IF NIM*NJM@=NeM THEN 109049 

149 PRINT “YOU DIDN'T ENTER THE WHOLE MATRIX" 
15% GOTO 16a 


Unlike the INPUT statement, no text string can be output with the MAT 
INPUT statement. For example: 


104 MAT INPUT "TEXT" AZ 
SYNTAX ERROR AT LINE 1923 


7.5 MATRIX INITIALIZATION STATEMENTS 


A matrix initialization statement allows the user to create ini- 
tial values for the elements of a matrix. The statement is of the 


form: 


(DIMI, DIM2) 


line number MAT <name>=<value> (DIM1) 


The name specified is the name of a predimensioned matrix, and the op- 
tional DIMI and DIM2 specifications indicate the size of the matrix 
to be initialized. When specified, DIM1 and DIM2 cause the matrix to 


be redimensioned. The value can be one of the following: 


Value Meaning 
ZER Sets all elements of the matrix to @ (this is 


true of all matrices when they are first cre- 
ated). (Function does not set row # or column 


g.) 

CON Sets all elements of the matrix to 1. (Function 
does not set row § or column @.) 

IDN Sets up an identity matrix (all elements are ¢ 


except for those on the diagonal, A(I,1I), which 
are 1). (Function does not set row @ or column 


g.) 
If no dimensions are indicated (DIM1 and DIM2 are not specified) 
in a matrix initialization statement, the existing dimensions of the 


matrix are assumed to be unchanged. For example: 


14 DIM AC193190)5BC015)sC€203,29) 

20 MAT A=ZER !SETS ALL ELEMENTS OF A=6 

34 MAT B=CONC19) {SETS FIRST 19 ELEMENTS OF Bl 
44 MAT C=IDNC19319) 


It should be noted that these instructions do not set row zero 


or column zero. 


7.6 MATRIX CALCULATIONS 


Mathematical operators and two intrinsic functions are available 
for use with matrices, 


7.6.1 Matrix Operations 


The operations of addition, subtraction, and multiplication can 


be performed on matrices using the common BASIC mathematical symbols. 


Each of the matrix operation statements is begun with the word 
MAT and followed by the expression to be evaluated. Each of the ma- 
trices involved must be predefined in a DIM statement. The subscripts 
of the matrices need not be indicated on the statement. The matrices 
indicated for any operation must be conformable to that operation. A 
subset of one matrix cannot be indicated as part of an Operation. 


116 DIM AC5M)s, PC25), COSA) 

129 “AT (=A+R 

FEINWH 

MATRIX LIMFNSION FREOR AT LINIE 120 
RFAnDY 


In order for line 120 to execute properly, line 110 should read: 


119 BIM AC5@),RC58),C054) 


Multiplication of conformable matrices is indicated as follows: 


14 NIM 6145595065919) sRO19919) 
299 MAT R = DC 


By conformable matrices is meant that the number of columns in matrix 
D is equal to the number of rows in matrix C. The dimensions of the 
matrix R must be large enough to contain the number of columns in D 
and the number of rows in C. The operation MAT A=A*B is illegal. 


Scalar multiplication of a matrix is performed as follows: 


115 MAT C = (K)*4 


Each element of matrix A is multiplied by the scalar value (constant, 


variable, or formula) K, indicated in parentheses. 
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The form MAT A=(K)*A is legal. Matrix A can be copied into matrix C 


(providing sufficient space is available in matrix C) as shown below: 


1240 MAT C=A4 
7.6.2 Matrix Functions 


Functions exist for the performance of transposition and inver- 


sion of matrices. 
159 MAT C=TRNCA) 


causes matrix C to be set equal to the transpose of matrix A. That 
is, C(I,J)=A(J,1) for all I,J; matrix C is redimensioned if necessary. 
For example: 

10 DIM X€15525)5N0551995M0555) 


75 MAT X=TRNCN) 
159 MAT NEINVCM) 


causes N to be computed as the inverse of matrix M (M must be a square 
matrix). After the inversion is complete, the function DET is set to 
the value of the determinant of matrix M. (If the matrix being in- 
verted is sufficiently singular to make it impossible to complete the in- 
version, the message CAN'T INVERT MATRIX is printed.) The value of DET, 


then, can be used as a variable in any formula. For example: 


269 MAT A = INVCX): DL=DET 
219 MAT B = INVCA): De@=DET 
220 IF Di=1/De GOTO 349 ELSE PRINT "“HELATIONSHIP THUE" 


Matrix inversion, like the other BASIC-PLUS matrix operations, 
does not operate on the elements of the row @ and column @ of the 
matrix; however, inversion destroys the previous contents of these 


elements. The operation MAT A = INV(A) is legal. 


CHAPTER 8 


ADVANCED STATEMENT FEATURES 


8.1 DEF STATEMENT, MULTIPLE LINE FUNCTION DEFINITIONS 
— Oe INE UN VEE ENE ES LUN 


In Chapter 3 the DEF statement is described as having the ability 
to create a one-line function which the user can call as an element in 
a BASIC statement. The user has, by now, probably felt the need for a 
user-defined function which can extend onto more than one line; such 
a facility is available. The format for a multiple-line function 


definition is as follows: 


line number DEF FN<identifier><(dummy arguments )> 
<body of definition> 


Zine number FNEND 


The multiple-line DEF function is distinguished from the one-line 
user functions by the absence of an equal sign following the func~- 
tion name on the first line. (From zero to five arguments of any 
type or mixture of types can be used.) The valuc returned by the 
function is the value of Fil<xidentifier> at the time the FNEND state- 
ment is encountered. Somewhere within the multiple-line definition 


there must be a statement of the form: 
Line number {LET} FN<identifier> = <expression> 


It is the value of this expression which is returned as the value of 
the function. (There may be more than one such statement, as in the 


example below.) 


The function example below determines the larger of two numbers 
and returns that number. The use of the IF-THEN statement is fre- 


quently found in multiple line functions as follows: 


19 DEF FAC%sY) 

a0 LET FNM=X 

39 IF Y<=X THEN 50 
44 LET FNM=Y 

52 FPNEND 


As another example, the following is a recursive! function that com- 


putes N-factorial: 


LISTNH 

19 DEF FNFCMA) 

29 IF MZ=12 THEN FNF=1 ELSE FNFSM2Z*FNFCM%Z-12) 
34 FNEND 

35 INPUT "VALUE FOR FACTORIAL"3™ 

40 PRINT M'FACTORIAL EQUALS"FNFCM) 

52 END 


READY 


RUNNH 
VALUE FOR FACTORIAL? 4 
4 FACTORIAL EQUALS 24 


READY 


Any variable referenced in the body of a function definition which is 
not an argument of that multiple line DEF function has its current 
value in the user program. Multiple-line DEF functions can be nested 
(one multiple-line definition can reference another multiple-line 
definition or itself). There must not be a transfer from within the 
definition to outside its boundaries or from outside the definition 
into it. The line numbers used by the definition must not be refer- 


enced elsewhere in the program. 


The parameters with which a user-defined function is called are 
strictly formal; attempts by the program to modify them are cancelled 


when the function exits to its calling program: 


LISTNH 

10 DEF FNBCX) 

26 X=4:3 FNB=14 
39 FNEND 

46 A=1: B=FNBCA) 
5% PRINT AsR 

63 END 


READY 


RUNNH 
1 1A 


READY 


IThe term recursive refers to an inherently repetitive process in which 
the result of each cycle is dependent upon the result of the previous 
cycle. 


A is not set to @ by the function FNB(A). However, any variable ref- 
erencec in the body of the function definition which is not one of the 
function arguments will retain, after exit from the function, any value 


assigned to that variable during the execution of the function. 


Functions cen be written in any type and can contain any variety 


of argument types. For example: 


LISTNH 

10 DEF FNASCASB,C2) 

af IF A>B GOTO 49 

39 FNAS=CHRSC(A+1): GOTO 54 

49 FNAS=CHRSCA+CZ) 

54 FNEND 

69 INPUT "VALUES FOR 45BsC2Z"3A,BsC¥ 

74 PRINT "FNAS$(As,BsCZ) = "FNAS(CAS BSCR) 
8A END 


READY 

RUNNH 

VALUES FOR AsBsCK? 365705924 
FNAS(€AsBsCZ) = «< 

READY 

RUNNH 

VALUES FOR AsBsC2? 4525506738 
FNASCAsB»sCZ) = 5 


READY 


8.2 ON-GOTO STATEMENT 


The simple GOTO statement allows the user to unconditionally 
transfer control of the program to another line number. The ON-GOTO 
statement allows control to be transferred to one of several lines 
depending on the value of an expression at the time the statement is 


executed. The statement is of the form: 
line number ON <expression> GOTO <list of Line numbers> 


The expression is evaluated and the integer part of the expression is 


used as an index to one of the line numbers in the list. For example: 


58 ON X¥ GOTO 1643,2005309 


transfers control to line number 1f9 if the value of X is 1, to line 
number 209 if X is 2, and to 3@f if X is 3. Any other values of X 
(other than 1, 2, or 3 in this example) cause an error message to be 
printed (or a transfer to an ON ERROR-GOTO routine with ERR=58). 


8.3 ON-GOSUB STATEMENT 


The GOSUB and RETURN statements are used to allow the user to 
transfer control of his program to a subroutine and return from 
that subroutine to the normal course of program execution (see 
Section 3.8 for details). The ON-GOSUB statement is used to condi- 
tionally transfer control to one of several subroutines or to one 
of several entry points to one (or more) subroutine(s). The state- 


ment is of the form: 


line number ON <expression> GOSUB <list of line numbers> 


Depending on the integer value (truncated if necessary) of the ex- 
pression, control is transferred to the subroutine which begins at 
one of the line numbers listed. Encountering the RETURN statement 
after control is transferred in this way allows the program to resume 
execution at the line following the ON-GOSUB line. 


An example of the statement follows: 


88 ON X-Y GOSUB 940+93321914 


When line 80 is executed, the value of X-Y being either 1, 2, or 3 
causes control to transfer to line 900, 933 or 1014, respectively. 
If the quantity X-Y is not equal to 1, 2 or 3, the error message:; 


ON STATEMENT OUT OF RANGE AT LINE 89 


is printed (or the user can transfer to an ON ERROR-GOTO routine with 
ERR=58). 


Since it is possible to transfer into a subroutine at different 
points, the ON-GOSUB statement could be used to determine which por- 
tion of the subroutine should be executed. 
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8.4 ON ERROR GOTO STATEMENT 


Certain errors can be detected by BASIC while executing a user 
program. These errors fall into two broad areas: computational 
errors (such as division by 9) and Input/Output errors (reading an 
end-of-file code as input to an INPUT statement). Normally the 
occurrence of any of these errors causes termination of the user 


program execution and the printing of a diagnostic message. 


Some applications may require the continued execution of a user 
program after an error occurs. In these situations, the user can 
execute an ON ERROR GOTO statement within his program. This state- 
ment tells BASIC that a user subroutine exists, beginning at the 
specified line number, which will analyze any I/O or computational 
error encountered in the program and possibly attempt to recover 


from that error. 
The format of the ON ERROR GOTO statement is as follows: 
line number ON ERROR GOTO {<line number>} 


This statement is placed in the program prior to any executable 
statements with which the error handling routine deals. If an error 
does occur, user program execution is interrupted and the user 

written error subroutine is started at the line number indicated. The 
variable ERR, available to the program, assumez one of the values listed 
in Table 8-1. Table 871 is also contained in Appendix C, the com- 


plete RSTS error message summary. 


When an error is encountered in a user program, BASIC checks to 
see if the program has executed the ON ERROR GOTO statement. If this 
is not the case, then a message is printed at the user's terminal and 
the program proceeds (if the error does not cause execution to 
terminate). If the ON ERROR-GOTO statement was executed previously, 
then execution continues at the specified line number where the 
program can test the variable ERR to discover precisely what error 


occurred and decide what action is to be taken. 


Table 8-l 


User Recoverable Errors 


(C) indicates that program execution continues, following printing of 


the error message, 


if an ON ERROR GOTO statement is not present. 


Otherwise, execution terminates and the system prints the READY mes-— 


sage. 


BAD DIRECTORY FOR DEVICE 


ILLEGAL FILE NAME 


ACCOUNT OR DEVICE IN USE 


NO ROOM FOR USER ON DEVICE 


CAN'T FIND FILE OR ACCOUNT 


NOT A VALID DEVICE 


I/O CHANNEL ALREADY OPEN 


DEVICE NOT AVAILABLE 


I/O CHANNEL NOT OPEN 


PROTECTION VIOLATION 


The directory of the device refer- 
enced is in an unreadable format 
or an attempt was made to perform 
a directory oriented access to a 
non-directory device. 


The filename specified is not ac- 
ceptable. It contains embedded 
blanks or unacceptable characters. 


The specified operation cannot be 
performed because the file is al- 
ready open by some user. This 
message has a general "file in use" 
meaning. 


Storage space allowed for the cur- 
rent user on the device specified 
has been used or the device as a 
whole is too full to accept further 
data. 


The file specified or current user 
account numbers were not found on 
the device specified. This message 
has a general "not there" meaning. 


Attempt to use an illegal or non- 
existent device specification 


An attempt was made to open one of 
the twelve I/O channels which had 
already been opened by the program. 


The device requested is currently 
reserved by another user. 


Attempt to perform I/O on one of the 
twelve channels which has not been 
previously opened in the program. 


The current user is not allowed to 
perform the requested operation on 
the specified file. Input may have 
been requested from an output-only 
device or vice versa. This message 
has a general "can't do that" mean- 
ing. 


Message Printed 


END OF FILE ON DEVICE 


FATAL SYSTEM I/O FAILURE 


USER DATA ERROR ON DEVICE 


DEVICE HUNG OR WRITE LOCKED 


KEYBOARD WAIT EXHAUSTED 


NAME OR ACCOUNT NOW EXISTS 


TOO MANY OPEN FILES ON UNIT 


ILLEGAL SYS() USAGE 


DISK BLOCK IS INTERLOCKED 


PACK IDS DON'T MATCH 


DISK PACK IS NOT MOUNTED 


DISK PACK IS LOCKED OUT 


ILLEGAL CLUSTER SIZE 


DISK PACK IS PRIVATE 


DISK PACK NEEDS 'CLEANING' 


Meaning 


Attempt to perform input beyond the 
end of a data file. 


An I/O error has occurred on the 
system level. The user has no 
guarantee that the last operation 
has been performed. 


One or more characters may have 
been transmitted incorrectly due 

to a parity error, bad punch com- 
bination on a card or similar error. 


User should check hardware condition 
of device requested. Possible causes 
of this error include a line printer 
out of paper or high-speed reader 
being off-line. 


Time requested by WAIT statement has 
been exhausted with no input received 
from the specified keyboard. 


An attempt was made to rename a file 
with the name of a file which already 
exists, or an attempt was made by 

the system manager to insert an ac- 
count code which is already within 
the system. 


Only one open DECtape output file 

is permitted per DECtape drive. Only 
one open file per magtape drive is 
permitted. 


Tllegal use of the SYS system func- 
tion. 


The requested disk block segment is 
already in use (locked) by some other 
user. 


The identification code for the 
specified disk pack does not match 
the identification code on the pack. 


No disk pack is mounted on the speci- 
fied disk drive. 


The disk pack specified is mounted 
but vcemporarily disabled. 


The specified cluster size is unac- 
ceptable. 


The current user does not have ac- 
cess to the specified private disk 
pack. 


Non-fatal disk mounting error; use 
CLEAN system call. 


Message Printed Meaning 


FATAL DISK PACK MOUNT ERROR 


Fatal disk mounting error. 


27 I/O TO DETACHED KEYBOARD I/O was attempted to a hung up data- 
set or to the previous, but now de- 
tached, console keyboard for the job. 


28 PROGRAMMABLE +C TRAP ON ERROR-GOTO subroutine was entered 
through a program trapped CTRL/C. 
See a description of the SYS system 
function. 
29 CORRUPTED FILE STRUCTURE Fatal error in CLEAN system call. 


not assigned 


VIRTUAL BUFFER TOO LARGE Virtual core buffers must be no 


more than 512 decimal bytes long. 


43 VIRTUAL ARRAY NOT ON DISK A non-disk device is open on the 
channel upon which the virtual 
array is referenced. 


44 MATRIX OR ARRAY TOO BIG In-core array size is too large. 


45 VIRTUAL ARRAY NOT YET OPEN An attempt was made to use a virtual 
array before opening the correspond- 
ing disk file. 


ILLEGAL I/O CHANNEL 


Attempt was made to open a file on 
an I/O channel outside the range of 
the integer numbers 1 to 12. 


47 LINE TOO LONG Attempt to input a line longer than 
255 characters (which includes any 
line terminator). Buffer overflows. 


48 FLOATING POINT ERROR Floating point overflow or underflow. 
(C) If no transfer is made to an 
error handling routine, a @ is re- 

turned as the floating-point value. 


49 ARGUMENT TOO LARGE IN EXP Maximum is in the range -89<arg<+&88. 
Value returned is zero. (C) 


not assigned 


51 INTEGER ERROR Attempt to use a number as an integer 
when that number is outside the allow- 
able integer range. (C) If no trans- 
fer is made to an error handling rou- 
tine, a J is returned as the integer 

value. 


52 ILLEGAL NUMBER Improperly formed input. For example, 
"1..2" is an improperly formed number. 

53 ILLEGAL ARGUMENT IN LOG Negative or zero argument to log func- 
tion. Value returned is the argument 
as passed to the function. (C) 

54 IMAGINARY SQUARE ROOTS Attempt to take square root of a number 


less than zero. The value returned is 
the square root of the absolute value 
of the argument. (C) 
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Message Printed Meaning 


SUBSCRIPT OUT OF RANGE Attempt to reference an array element 
beyond the number of elements created 
for the array when it was dimensioned 


CAN'T INVEFT MATRIX Attempt to invert a singular matrix. 


OUT OF DATA The DATA list was exhausted anda 
READ requested additional data. 


ON STATEMENT OUT OF RANGE The index value in an ON-GOTO or 
ON-GOSUB statement is less than one 
or greater than the number of line 
numbers in the list. 


NOT ENOUGH DATA IN RECORD An INPUT statement did not find 
enough data in one line to satisfy 
all the specified variables. 


INTEGER OVERFLOW, FOR LOOP The integer index in a FOR loop 
attempted to go beyond 32766 or 
below -32766. 


DIVISION BY @ Attempt by the user program to divide 
some quantity by zero. (C) If no 
transfer is made to an error hand- 
ling routine, a @ is returned as 
the result. 


8.4.1 RESUME Statement 


After the problem is corrected (if this is both possible and 
desired by the program), execution of the user program can be resumed 
through use of the RESUME statement (which is placed at the end of 
the error handling routine, much like a RETURN statement in a normal 
subroutine). The RESUME statement causes the program statement that 
originally caused the error to be reexecuted. If execution is to be 
restarted at some other point within the program (as might be the case 
for a non-correctable problem), the new line number can be specified 


in the RESUME statement at the end of the error handling routine. 


The format of the RESUME statement is as follows: 
Line number RESUME {<line number>} 
For example: 
P495% RESUME 
e041 RESUME 1288 
The line 2880 restarts the user program at the line in which the 
error was detected, and is equivalent to the statement: 


2004 RESUME VY 


Line 2001 above restarts the user program at line 100 (which can be 


used to print some terminal message for that particular operation). 


A RESUME statement should always be included in the error hand- 


ling routine. 


8.4.2 Disabling the User Error Handling Routine 


If there are portions of the user program in which any errors 
detected are to be processed by the system and not by the user program, 
the error subroutine can be disabled by executing the following state- 


ment: 


line number ON ERROR GOTO 9 


which returns control of error handling to the system. An equivalent 


form is: 


line number ON ERROR GOTO 


in which case line @ is assumed. Executing this statement causes the 
system to treat errors as it would if no ON ERROR GOTO had ever been 
executed. 


Generally, the error handling subroutine detects and properly 
handles only a few different errors; it is useful to have the RSTS 
system handle other errors, if they occur. For this reason, RSTS 
allows the ON ERROR GOTO @ statement to be executed within the error 
subroutine itself. Special treatment is accorded this case, in that 
the disabling occurs retroactively; the error which caused entry to 
the error subroutine is then reported and a message printed as though 
no ON ERROR GOTO statement had been in effect. 


As an example of this feature, consider an application in which 
inexperienced users interact with a BASIC program. These users may 
not know what to type at the terminal, and the program may want to 
prompt them. The program tells the system to allow up to 60 seconds 
for the user to respond (via the WAIT function, described in Section 
8.8 ) and then to alert it that the user has not replied. The program 


then prints additional information for the user. 


10 ON ERROR GOTO 1999 {SET UP ERROR ROUTINE 


2A WAITC69) WAIT 64 SECe FOR REPLY 
30 INPUT "YOUR WAME"3NS !GET STUDENT NAME 
50 STOP 


* 
4 


t 


1999 !THIS IS THE ERHOR HANDLING ROUTINE 

1919 IF EkR<>15 THEN ON ERROR GOTU @ !WAIT ERRORS ONLY 
1920 PRINT SKIP TO NEV LIWE 

1434 PRINT “PLEASE TYPE YOUR NAME" 

1949 PRINT "AND THEN HIT THE 'RETUEN' KEY" 

16549 RESUME !TRY AGAIN 


In this example, if the call to the error subroutine was caused by 
some error other than the KEYBOARD WAIT EXHAUSTED error, the program 
would exit via the ON ERROR GOTO @ in line 119. This permits the 
appropriate error message to be printed on the user's terminal. Note 
that exiting via the RESUME at line 195 causes the INPUT statement to 


be restarted. 


8.4.3 The ERL Variable 


It is sometimes useful to be able to recognize the line number 
at which an error occurred. Following an error detection, the integer 


variable ERL contains the line number of the error. 


ERL would be used, for example, to indicate which of several 
INPUT statements caused an END OF FILE error. 


Care must be taken in use of the ERL variable since changing or 
resequencing the line number field of all or some statements within 
the program can alter the value of the ERL variable as it appears 


within an expression context. For example: 


19 ON FRROF GOTO 1288 

PA INPUT "TYPE TeO NON-ZERO NUMBFRE ASR 
3% LET x=As?D 

49 LET X=X+P/A 

59 PRINT X 

€Q STCP ‘ 


199 IF FRE<>61 THEN ON 7.KROF GOTO @ 
110A PRINT "FIRST NOMBER LAS 3 ITF FRLS a6 
1°40 PRINT "SECOND NUMPER WOO 6" ITP FrRL=3n 


LISINH 
16 INPUT As BsC 
29 IF A>R THEN 
IF R>C THEN PRINT "A>R>cn 
FLSF IF C>A 
THEY FRINT "C>Aa>R" 
FLEE PEINT "A>C>RY 
ELSE IF A>C THEN PRINT "R>a>ce 
FLSE Ik BC 
THEN FRINT "R>C>a' 
FLSE FRINT "C>R>Aa™ 
39 FVD 


FFABY 
FUNNH 

? Ps9s21 
C> RA 
READY 
FUNNH 

? BsFs} 


> A>C 


BRADY 


The use of the LINE FEED and TAB characters greatly improves the 
legibility of complex program statements such as line 20 above. 


The IF-THEN-ELSE statement can appear anywhere in a multiple- 
statement line. However, if this statement is followed by any other 


statements, the following rules apply: 


a. The physically last THEN or ELSE clause is considered to be 
followed by the next statement on the line: 


10 IF A=1 THEN 1060 FLSF PRINT At PRINT "ONE" 


where A#l, the value of A and the text string ONE are printed. 


b. All other THEN or ELSE clauses are considered to be followed 
by the next line of the program: 


P® IF A>R THEN IF B<C THEN FRINT "R<C": GOO 30 
25 PRINT "A<RB! 


Only in the case where "B<C" is printed is the statement 
GOTO 38 seen and executed. 


If either A<B or B>C, the line "A<B" is printed. 


8.6 CONDITIONAL TERMINATION OF FOR LOOPS 


In the simple FOR-NEXT loop described in Section 3.6.1, the for- 


mat of the 


FOR statement is given as: 


line number FOR<variable>=<expression>TO<expresston>{STEP<expression>} 


There are many situations in which the final value of the loop variable 


is not known in advance and what is really desired is to execute the 


loop as many times as necessary to satisfy some condition. 


In evaluat- 


ing a function, for example, this condition might be the point at which 


further iterations contribute no further accuracy to the result. 


BASIC-PLUS provides a convenient way of specifying that a loop is to 


be executed until a certain condition is detected or while some con- 


dition is true. 


line numberFOR<variable>=<expression>{STEP<expression>} WHILE< 


and 


line numberFOR<variable>=<expression>{STEP<expresston>} UNTIL< 


These statements take the forms: 


relational, 
expresston 


relational, 
expresston 


The condition has the same structure as specified in an IF statement 


(see Section 3.5) and can be just as elaborate, if necessary. 


Before 


the loop is executed and at each loop iteration the condition is tested. 


The iteration proceeds if the result is true (FOR-WHILE) or false 


(FOR-UNTIL) . 


The difference between a FOR loop specified with a WHILE or UNTIL 


and one svecified with a terminal value for the loop variable is 


worth noting, in order to avoid potential pitfalis in the usage of 


each. Consider the two loops in the program below: 


LISTNH 


16 
15 
28 
25 
5a 
55 
40 
65 
T5 


FOR [21 TO 10 
PEINT 13 

NEXT I 

PHINT "T="1 

FOR I=1 UNTIL 1>10 
PRINT 13 

NEXT I 

PHINT "T="1 

FVD 


RFA DY 


RUNNH 


1 


@e 3 4 5 6 7 86 9 19 I= 
@ 3 4 5 6 7 8 9 108 I= 


READY 


10 
ll 


Each of these loops prints the numbers from 1 to 10. When the loop 
at line 10 is done, however, the loop variable is set to the last 
value used (that is, 10). In the second loop beginning at line 50, 
the loop variable is set to the value which caused the loop to be 


terminated (that is, 11). 


Next consider the two loovs following: 


LISINH 

19 X=10 

e@ FOR I=1 TO X 

20 X=X/22: PRINT I5% 

4% NEXT I 

54 PRINT 

60 X=10 

70 FOR [=1 UNTIL I>xX 
8@ R=X/Pt FRINT 5X 


94 NEXT I 
95 END 
HEADY 
RIINVH 
1 5 
2 2.5 
3 1.25 
4 0625 
5 0315 
é 15625 
7 eATB1PS 
tal » B9AFPSE-} 
9 °©195313F-1 
14 ©ITA5A3BR-P 
1 5 
2 eS 
READY 


In the case of the loop beginning with line 20, the iteration stops 
when I exceeds the initial value of X (that is, 10). Even though the 
value of X changes within the loop, the initial value of X determines 
the performance of the loop. In the second loop, the current value 
of X determines when the iteration ceases. Thus, after three itera- 
tions, I is greater than X in the second loop and the loop is termin- 
ated. (The STEP value when omitted, is still assumed to be 1.) 


These forms of loop control are particularly useful in iterative 
applications where data generated during the loop execution determines 


loop completion. 


Consider the problem of scanning a table of values until two 


successive elements are both 0, or the end of the table is reached: 


156A FOR I=! UNTIL I=N OR XCID=0 AND KCI+1)=6 
115 NFXT I 


° 


The following two programs also illustrate the FOR-UNTIL and 
FOR-WHILE constructions: 


LISTNH 

160 INPUT "LETTEF IS's Y% 

PA KXEe"'s FOR T=] UNTIL Xf=Y¢ OF XFE"ZZ2" 

2A KFEAD X&: NEXT I 

44 DATA AsPsCs Ds Fs Fs Cote Ta Jo Ko Lo MaNo Oo Po Ms Bs Ss Talis Veoh e Xa Ya Lo ZZZ 
S PRINT “LETTER IS NUMBER'I-1 

90 END 

RRADY 

PUNNH 


LETTER IS? C 
LETTER IS NUMBER 3 


FFADY 


FUNNH 
LETTER IS? Q 
LETTER IS NUMBER 17 


READY 


LISTNH 


19 
20 


INPUT "WORDS YS 
AS=""3 FOR [=i WHILE Xf<s¥% 


32 PFEAD Xf: NEXT I 

40 DATA Ass Cs Ds Fo Fs Go He le Js Kalo MoNs Os Pos Os Ka So Tails Va Ua Xe Ya Zo ZZZ 
5A PRINT “WORD PEGINS WITH LETTER" I-2 

98 END 

READY 

RUNNH 


VOED? FIRST 
vORD BEGINS WITH LETTER 6 


FFA DY 


RUNNH 
WORD? LAST 
WORD BEGINS WITH LETIFR 12 


READY 


8.7 STATEMENT MODIFIERS 


To increase the flexibility and ease of expression within BASIC- 
PLUS, five statement modifiers are available (IF, UNLESS, FOR, WHILE, 
and UNTIL). These modifiers are appended to program statements to 
indicate conditional execution of the statements or the creation of 


implied FOR loops. 


8.7.1 The IF Statement Modifier 


The form: 
<statement>IF<condttton> 
is analogous to the form: 


IF<condi tion>THEN<statement> 


For example: 


1@ PRINT X IF X<>@ 
is the same as: 


19 IF X<>@ THEN PRINT X 


The statement is executed only if the condition is true. 


When a statement modifier appears to the right of an IF-THEN 
statement, then the modifier operates only on the THEN clause or the 
ELSE clause, depending on its placement to the left or right of ELSE. 


For example: 


190 IF 1=1 THEN PRINT “HELLO” ELSE PRINT "BYE" IF 1=@ 


will print: 


HELLO 


since the test l=1l is true. The modifier IF l= is false, but 


as it applies only to the ELSE clause, it is never tested. 


It is not possible to include an ELSE clause when using the 


modifier form of IF. 
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Several modifiers may be used within the same statement. For 


example: 


74 PRINT XCIsJ) IF I=J IF XCIsJ)<>0 


which will print the value of X(I,J) only if the value of X(I,J) is 
non-zero and if I equals J. Whenever there is more than one modifier 
on a line, the modifiers are executed ina right-to-left order. 

That is, the rightmost one is executed first, and the leftmost one is 
executed last. This situation is described by the term "nested 


modifiers". 


An additional operational advantage of this interpretation of IF 
modifiers is illustrated in the discussion of FOR modifiers in Section 
8.7.3. 


8.7.2 The UNLESS Statement Modifier 
The form: 


<statement> UNLESS <conditton> 


causes the statement to be executed only if the condition is false. 


For example, the following statements are all equivalent: 


10 PRINT A UNLESS A=6 

°@ PRINT A IF NOT A=@ 

30 IF NOT A=@ THEN PRINT A 
4@ IF A<>@ THEN PRINT A 


This particular form simplifies the negation of a logical condition. 


8.7.3 The FOR Statement Modifier 
The form: 
<statement>FOR<vartable>=<expression>10<expresston>{STEP<expresston> } 
or, the form 


<s tatement>FOR‘variable>=<expresston> {STEP<expression>} [wernt corercooton> 


can be used to imply a FOR loop on a single line. For example (using 
none of the optional elements): 


1% PRINT Is SARCI) FOR I=t TO 14 


This statement is equivalent to the following FOR-NEXT loop: 


26 FOR I=) TO 18 
25 PFINT I»SQRC1I): NEXT I 


In cases where the FOR-NEXT loop is extremely simple, the necessity 
for both a FOR and a NEXT statement is eliminated. Notice that this 
implied FOR loop will only modify (and hence execute iteratively) one 


statement in the program. Any number of implied FOR loops can be used 


in a single program. 


As in the case with all modifiers, a FOR modifier in an IF state- 
ment operates only on the THEN or ELSE clause with which it is associ- 
ated, and never on the conditional expression to the left of the THEN. 
Thus, if it was desired to print all non-zero values in a matrix X(199), 
the following program would not operate properly: 


16 DIM XC€160) 
15 READ XCI) FOR I=1 TO 109 
20 IF X€1)<>@ THEN PEINT I2XCI) FOR I=! TO 186 


since the implied FOR loop at line 20 applies only to the THEN PRINT... 

part of the statement, and not to the IF... part. The first value of xX 

tested is X(100), since I remained at 100 from statement 15. To achieve 
the desired effect, it is only necessary to state line 20, not as an IF 

statement, but rather as a PRINT statement with nested modifiers; for 


example: 


26 PRINT IsXC1) IF XC1)<>@ FOR I=1 10 196 


when expressed in the latter form, the nested modifier rule takes effect, 
and all the values of X(I) are tested and printed as appropriate. 


The WHILE and UNTIL clauses are explained in Section 8.6. 


8.7.4 The WHILE Statement Modifier 


The form: 


<statement> WHILE <conditton> 


is used to repeatedly execute the statement while the specified con~ 


dition is true. For example: 
1@ LET X=Xte WHILE Xte<1lE6 
is equivalent to: 


10 LET xX=xt12 
1S IF X<1E6@ THEN 186 


The WHILE modifier (and the UNTIL modifier in Section 8.7.5) operates 
usefully only in iterative loops where the logical loop structure modi- 
fies the values which determine loop termination. This is a significant 
departure from FOR loops, in which the control variable is automatically 
iterated; a WHILE statement need not have a formal control variable. 

The following statements never terminate properly; such program se- 


quences are called infinite loops: 


1@ xX=X+1 WHILE 1<1980 
15 PRINT IsACI1) WHILE ACI)<>6 


In both cases, the program fails to alter the values which are used to 
determine when the loop is done. 


A successful application of the WHILE modifier is shown below: 


5 !TEST OF SQUARF ROOT HKOUTINE 
19 X=X+1 VHILE xX=SQRCKt 2) 
22 PRINT X 


8.7.5 The UNTIL Statement Modifier 


The form: 
<statement> UNTIL <condition> 


is used to repeatedly execute the statement until the statement be- 
comes true; which is to say, while the statement is false. For 


example: 


19 X=x+1 UNTIL X<>SORCX1 2) 


is the same as 


1% X=X+1 
20 IF ReSORCX12) THEN 19 


8.7.6 Multiple Statement Modifiers 


More than one modifier can be used in a single statement. Multiple 


modifiers are processed from right to left. For example: 


10 LET A=B IF A>® IF BO 


which is equivalent to: 


160 IF B>@ THEN IF A>@ THEN A=B 


or 
10 IF B>@ AND A>@ THEN LET A=R 


or 
16 IF R<=@ THEN 48 
28 IF A<=0 THEN 46 
39 LET A=R 


A two dimensional matrix (m by n) can be read one row at a time as 


follows: 


58 READ ACIsJ) FOR J=!] TO ™ FOR T=! TON 


which is equivalent to: 


54 MAT HEAD ACNs™M) 


and to: 


39 FOR I=] TO N 
55 FOR J=1 TO ™ 
60 SEAD ACIsdJ) 
65 NEXT J 

73 NEXT I 


Also see Section 8.7.3 which described the interaction of FOR and IF 
modifiers. 


8.8 SYSTEM FUNCTIONS AND STATEMENTS 


RSTS-1l has several system functions which allow the user to 
obtain certain information about or perform operations with the 


system. The functions are described in Table 8-2, 


Table 8-2 


SYSTEM FUNCTIONS 


_ 


DATES (9) 


DATES (N) 


TIMES (@) 


TIMES (N) 


TIME (2) 


TIME (1) 


TIME (2) 


SWAPS (1%) 


RADS (13%) 


returns the current day, month 
and year, in the form: 


2-Mar-72 


Note that the date contains 
both upper and lower case 
characters (where lower case 

is not available on some ter- 
minals, only upper case letters 
are used). 


returns a character string cor- 
responding to a calendar date. 
The formula used to translate 
between N and the date is as 
follows: 


(day of year)+[(number of years 
since 1970) *192) 


DATES (1) = "@1-Jan-79" 
DATES (296%) = "29-Feb-72" 


returns the current time of day 
as a character string as fol- 
lows: 


TIMES (9) = "85:39 PM" 
returns a string corresponding 


to the time at N minutes before 
midnight, for example: 


TIMES (1) = "11:59 PM" 
TIMES (1448) = "12:99 AM" 
TIMES (721) = "11:59 AM" 


N must be less than 1441 to 
return a valid string. 


returns the clock time in sec- 
onds since midnight. 


returns the central processor 
(CPU) time used for this job 
in 9.1 second quanta. 


returns the connect time (time 
during which the user has been 
logged into the system) for this 
job in minutes. 


causes a byte swap operation 
to occur on the integer vari- 
able 1%; returns the value of 
I% with the bytes swapped. 


converts an integer to a 3- 
character string. This func- 
tion is used to convert a value 
(expression in Radix-5@ format), 
back into ASCII. Radix-5@ is 


explained in Appendix D. 
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PRINT DATES(@) 
19-AUG-72 


READY 


155 PRINT X%2C1)» DATESCI) 


75 IF TIMES€@) >= "@5:45 Pm" 
THEN PRINT “TIME TO QUIT" 


PRINT TIMES(C1) 
11:59 PM 


READY 


PRINT TIMESC1400) 
le: 49 AM 


READY 


25 IF TIMECA)>43200 
THEN PRINT “AFTERNGOV" 


1@ IF TIMEC1)>394 THEN STOP 


10 IF TIMEC2)>18@6 THEN STOP 


19 PRINT CHRSCSWAPZCIZ)) 


S55 PRINT RADSCI2) 


There are also two special system statements that can be used 
within a BASIC-PLUS program; these are SLEEP and WAIT. Both state- 
ments allow the user to suspend his program for a stated interval. 


The SLEEP statement is of the form: 
line number SLEEP <expresston> 


SLEEP is used to dismiss the currently running program for the number 
of seconds indicated by the expression. At the end of this period the 
program is again runnable. Thus, the user is guaranteed at least this 
number of seconds idle time, possibly slightly more depending upon the 
number of jobs currently active on the system. 


The WAIT statement is of the form: 


line number WAIT <expresston> 
WAIT is used to set a maximum period for the system to wait for input 
from the user keyboard. If no delimiter is typed at the keyboard 
(RETURN, LINE FEED, ESCAPE) within the number of seconds specified by 
the expression, the program is restarted and a WAIT EXHAUSTED error 
occurs, which can be detected using ON ERROR-GOTO. The WAIT statement 
is used in conjunction with the INPUT statement. As an example: 


LISTNH 

1@ GN ERROR GOTO 136 
23 WAIT 15 

33 INPUT "16416 =" A 
49 WAIT @ 


50 IF A=32 THEN PRINT "RIGHT!" 
ELSE PRINT "NOs TRY AGAIN": GOTG 18 
74 STOP 
109 IF ERR<>15 THEN OW ERHOK GOTO @ 
11@ PRINT "WAKE UPI" 
lef RESUME 39 
134 END 


READY 


RUNNH 

16+16 =? WAKE UP! 
16+16 =? 21 

NOs TRY AGAIN 
16+16 =? 32 
RIGHT! 


In this example line 189 is executed only if the user fails to 
respond within 15 seconds. The use of WAIT g restores the terminal 
to its normal state in which no timeout occurs, but rather the 


system waits until a line is entered, however long that may take. 
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PART III 


BASIC-PLUS I/O 


This part of the manual contains a complete 
description of all BASIC-PLUS I/O operations. 
A brief review Is made of the simple forms of 
READ, DATA, PRINT, RESTORE and INPUT along 
with the more advanced forms of these state- 
ments. Virtual core matrices, Record I/O and 
device dependent operations are also described. 


Itt 


CHAPTER: 9 
DATA STORAGE CAPABILITIES 


9.1 FILE STORAGE 


Previously, techniques have been presented for entering data 
into a program as the program is written (via READ and DATA statements) 
or from the user terminal while the program is executing (via the 
INPUT statement). Both techniques are inefficient when the amount of 
data to be read or written increases beyond a few items. In order to 
improve operation, BASIC-PLUS provides the user with facilities to 
define and manipulate Input/Output data files. 


A BASIC-PLUS data file consists of a sequence of data items 
transmitted between a BASIC program and an external Input/Output de- 
vice. The external device can be the user terminal, some other 
terminal, disk, line printer, card reader, Magnetic tape device, 
DECtape, or high-speed paper tape equipment. 


Each data file has both an external name by which it is known 
within the RSTS system (the name of the file on a disk storage device, 
for example) and an internal file designator (a number used to ref- 
erence the file). An OPEN statement (see Section 9.2) is used to 


associate an external file specification with an internal file channel. 


An external file specification contains some or all of the 
following information: 


device: filename, extenston|proj,prog]<protection> 


If the device designator is not present in a file specification, the 
system device (public structure)*is assumed. For non-file-structured 
devices, only the device designator need be specified; any filename, 


extenston, project-programmer codes, and proteetton code specified 


are ignored. 


“More information on public and private disks can be found in Chapter 
12. 


Where a device designator appears, it can be one of the following: 


Device 
Designation 


File-Structure devices 


DF: 

DFG: 
DK@: 
DP@: 


DTG: 


Table 9-1 


Device Designations 


Device 


RSTS public disk structure as a whole 


RF11 disk 
RK11 disk pack units @ through 7 
RP11 disk pack units § through 7 


DECtape units @ through 7 
Industry compatible magnetic tape units @ 


through 7 (magnetic tape can also be treated 
as a non-file-structured device) 


Non-File-Structured devices 


PR: 
PP: 
LP: 


to KB16: 


High-speed paper tape reader 
High-speed paper tape punch 
Line printer 

Card reader 


current user terminal 
other user terminals on the system 


For file-structured devices, each file is assigned a ftlename and 


extenston. The filename is a string of one to six alphanumeric char- 


acters. The filename extension consists of a dot (.) followed by a 


one to three alphanumeric character string, usually specifying the 


file type. A null or blank extension is permitted, in which case the 


dot and filename extension field are omitted from the file designa- 


tion. The extensions recognized by the RSTS-11 system are as follows: 


Table 9-2 


Reserved File Extensions 


Extension Significance 


indicates a BASIC-PLUS 
source program to be 
compiled; stored in 
ASCII format. 


indicates a compiled 
BASIC-PLUS program; 


Automatically 
Appended on Output 


to BASIC-PLUS source 
programs stored with 
a SAVE or REPLACE 
command. 


to BASIC-PLUS pro- 
grams on which a 


Assumed on 
Input 


by the OLD command, 
also assumed by RUN, 
CHAIN and UNSAVE in 
the absence of a.BAC 
file of the same name. 


by the RUN, CHAIN and 
UNSAVE commands. 


COMPILE command is 
performed. 


stored in a binary 
format, cannot be 
altered. 


indicates RSTS Monitor 
files 


indicates a temporary 
BASIC-PLUS file. These 
files are used while 
creating or editing a 
BASIC program. They 
are deleted when no 
longer needed. 


The [proj,prog] field (containing the project and programmer num- 
bers) identifies the owner of the file. If it is omitted the owner 
is assumed to be the current user. This field is meaningful only for 
disk and magtape files; it has no significance for DECtape files or files 
on non-file-structured devices. The two numbers forming the field 
are decimal numbers between 1 and 254, separated by a comma, and 


enclosed in square brackets. 


NOTE 


The PDP-11 DOS Monitor uses octal UIC 
values in the range 1,1 to 376,376. 
Transferring magtape files between 
RSTS and DOS causes an effective 
decimal-to-octal conversion between 
RSTS project-programmer number and 
DOS UIC code. RSTS DECtape files are 
assigned a [1,1] UIC code. 


Use of the $ character (dollar sign) in the project-programmer 
field indicates that the file is stored under the system library 
account ([1,2]). 


When creating a file (with OPEN or OPEN FOR OUTPUT, see Section 
9.2) or renaming a file (with the NAME AS statement, see Section 9.7) 


a protection field can be specified. Files can be read and/or write 


protected against three classes of users where distinctions are made 
on the basis of the project and programmer number of the user attempt-— 


ing to access the file. The three classes of users are: 


a. owner; 


b. group, all users having the same project number as the 
owner (termed the owner's group); and 


c. others, all other users not in the owner's group 


The following table is used to determine the value of the protection 
code to achieve the desired file protection: 


Table 9-3 


Protection Codes 


Meaning 


read protect against owner 
write protect against owner 


read protect against owner's group 
write protect against owner's group 


read protect against all others not in 
owner's group 
write protect against all others not in 
owner's group 


Protection codes are stored within the system as character strings and 
consist of a one-or two-digit decimal number within paired angle 
brackets. The decimal number is the sum of the desired combination of 
protection code values contained in Table 9-3. For example: a pro- 
tection code of <48> would deny read or write access to anyone logged 
into the system under an account number whose project number differs 
from the owner. The code <48> is the sum of 32 (write protect against 
all others) and 16 (read protect against all others). Similarly, the 
code <42> protects a file against any write operations (32=write pro- 
tect against all others, 8=write protect against other group members, 


and 2=write protect against owner, 42=32+8+2). 


Protection codes are normally specified only in the NAME AS state- 
ment which allows the user to change the name and protection code of 


any file which he has previously created (see Section 9.7). However, 


protection codes can be specified as an optional part of any filename. 


For example, 


OLD FILE-BAS<6@> 
which would be equivalent to 


OLD FILEeBAS 


or 


OLD FILE 


In creating disk files a default protection code of 
<69> is supplied. This permits only the owner to access the file, 
(The file is read and write protected against everyone but the owner, 
since code <6fs= 32 + 16 + 8 + 4). For example, the command 


SAVE FILE1 


READY 


saves the current BASIC-PLUS program as FILE1.BAS with a protection 
code of <60>. 


9.2 OPEN STATEMENT 


The OPEN statement associates a file on a file-structured device 
or some non-file-structured device with an I/O channel number inter- 


nal to the BASIC program. BASIC-PLUS permits up to 12 files to be 


open at a given time, and, therefore, permits internal file designa- 


tors to be integers between 1 and 12. 


The general form of the OPEN statement is as follows: 


: FOR INPUT . 
L < > 
line number OPEN <string> {FOR output! AS FILE <expresston 


One or more of the following specifications can be appended to the 
end of the statement (and are described in Sections 9.2.1 and 9.2.2): 


{,RECORDSIZE <expression>} {,CLUSTERSIZE <expresston>} 


The string field is a character string constant, variable or expres- 
sion that contains the external file specification (as described in 
Section 9.1) of the file to be opened. The AS FILE expression 
must have an integer value between 1 and 12, corresponding to the 
internal channel number on which the field is being opened. 


There are three distinct forms for the OPEN command: 


OPEN<string> FOR INPUT 
OPEN<string> FOR OUTPUT 
OPEN<s tring> 


The form of the OPEN statement used determines whether an existing 
file is to be opened or a new file created. 


a. An OPEN FOR INPUT statement causes a search for an already 
existing file (since the statement indicates the file is 
an input file). If no file is found, the FILE NOT FOUND 
error occurs. For example: 


50 OPEN "FILE+«DAT" FOR INPUT AS FILE 1 


b. An OPEN FOR OUTPUT statement causes a search for an already 
existing file which, if found, is deleted. A new file is then 
then created. 


75 OPEN "DATA-@1<49>" FOR OUTPUT AS FILE 3 


c. An OPEN statement without an INPUT or OUTPUT designation 
attempts to perform an OPEN FOR INPUT operation as 
described above. If this fails, a new file is created. 


{3% OPEN "“MATR-TER™ 4S FILE 7 


The OPEN statement does not control whether the program attempts 
to perform input or output on the file or whether read and/or write 
access to the file is granted!; these privileges are controlled by 
the file protection code. 


1Magtape is an exception to this rule, see Chapter 12. 


If an assignable device (all devices other than disks are avail- 
able or assignable to a single user at any given time) is referenced 
in any OPEN statement and that device is already in use by another 
user, a DEVICE NOT AVAILABLE error occurs. 


When used with disk files, an OPEN FOR INPUT or OPEN FOR OUTPUT 
allows either read or write operations on the opened file. However, on 
DECtape and magnetic tape devices, the FOR INPUT and FOR OUTPUT clause 
restricts operations on that file to the type of operation specified. 


NOTE 


Only one person can have write access to a file at a 
Single time (unless UPDATE mode is used, see Section 
12.2); and user write access is always denied to a 
file with a .BAC extension, since compiled files can 
only be run. 


The next two sections in this manual describe the RECORDSIZE 
and CLUSTERSIZE options of the OPEN statement. As these are sophis- 
ticated file handling tools, it is suggested that the novice user 
initially skip these sections and continue with Section 9.2.3. 


9.2.1 RECORDSIZE Option 


When any file is opened, the system creates a buffer area in the 
user's core space to buffer all I/O to and from the file. Normally 
the amount of space reserved is determined by the device, as each 
device has a default device buffer size as described in Table 9-4. 


Table 94 


Default Device Buffer Sizes ~ 


Default Device Buffer size | 


disk (DFn:,DKn:,DPn:) 


characters 


characters 


DECtape (DTn:) 


Magtape (MTn:) characters 


High-speed reader (PR:) characters 


High-speed punch (PP:) characters 


Line printer (LP:) characters 


Card reader (CR:) characters 


User terminal (KB:) characters 


With the RECORDSIZE option the user program can specify the 
allocation of more buffer space than is provided by the default case. 
However, in some cases the particular device driver may not permit 
additional space to be used. For example: 


Table 9-5 
Use of RECORDSIZE 


Device Possible Buffer Alterations 


Disk The disk drivers permit use of any 
buffer size that is an even multiple 
of 512 bytes. 


DECtape The DECtape driver uses only the first 
510 bytes of the available buffer 
space, 


Magtape File-structured magtape uses only 
the first 512 bytes of the avail- 
able buffer space. Non-file- 
structured magtape can use any 
buffer size (see Section 12.3.4). 


High-speed reader 
High-speed punch These non-file-structured devices 


Line printer can use any selected buffer size. 
User terminal 


Card reader The card reader driver uses only the 
first 82 characters of the available 
buffer space. 


The RECORDSIZE option has significant advantages when used with 
Magtape and disk files, RECORDSIZE permits non-file-structured access 
to magtape records of any length (see Section 12.3.4 ). On a disk 


file, total throughput can be improved by using a larger buffer size 
as this permits a single disk transfer to read a large quantity of data. 
As an example of the use of the RECORDSIZE option: 


190 OPEN "MASTER+«DAT" FOR INPUT AS FILE 145 RECORDSIZE 29468% 


If the file MASTER.DAT were on an RF11 disk and occupied a contiguous 
area on that disk, a 2948-byte transfer would take about 33ms while 
four 512-byte transfers would take about 83ms (on the average). If the 
file did not reside in a contiguous disk area, the RSTS Monitor would 
break the 2948-byte transfer into four 512-byte transfers. Even in 


this last case, the system overhead to perform the transfer would be 
less. 


This example raises the question of how to ensure that a file 
occupies a contiguous disk area. This can be done by means of the 
CLUSTERSIZE option described in the following Section. 
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9.2.2 CLUSTERSIZE Option 


The CLUSTERSIZE option is applicable only to disk files and only 
when these files are initially created with an OPEN or OPEN FOR OUTPUT 
Statement. The CLUSTERSIZE specification is ignored if this is not 


the case. 


The RSTS system divides each disk into a number of 256-word 
blocks. Each block is assigned a unique physical block number be- 
tween 1’ and 65,535. Physical block numbers are assigned such that 
block n is physically contiguous with blocks n+l and n-1l, 


A number of contiguous blocks taken together as a unit are called 
a cluster. RSTS permits clusters to be 1, 2, 4, 8, 16, 32, 64, 128 
or 256 blocks long. When the disk is refreshed (the process by which 
the disk is initialized, or cleared, for use on RSTS) a minimum 
cluster size can be established. This minimum cluster size (also 
called the pack cluster size) can be 1, 2, 4, 8 or 16 blocks (normally 
the pack cluster size is a single block long). 


For each file on the system, an entry is made in the owner's 
file directory (User File Directory or UFD) containing the filename, 
cluster size for the file, and a sequential list of blocks belonging 
to that file. 


A UFD has a fixed maximum size which is determined when the UFD 
is created”. A UFD on any one disk cannot exceed 112 (decimal) blocks 
(28,672 words). If all files were a minimum size (7 or fewer clusters 
long) a UFD would have room for a maximum of 1157 files. To keep the 
list of blocks belonging to the file as short as possible, the UFD con- 
tains a one-word entry for the first block of each cluster. Knowing the 
first block number of the cluster and the number of blocks in the 
cluster is sufficient to determine all of the blocks in the cluster. 


Block § of each disk is reserved for a bootstrap record and is 
not used by any file. 


The maximum size of a UFD is seven times the cluster size for 

that UFD, which is established when the UFD is created, and May be 
1, 2, 4, 8 or 16 blocks. The figures given in the text assume 

a UFD cluster of 16. 


Because of the size limit on the UFD, large files benefit from 
the specification of large cluster sizes. In an extreme example, the 
UFD would be completely filled by a single file of 24,283 blocks 
where the file cluster size is one block. However, with a cluster 
size of 256 blocks, only 128 words of the UFD are required to describe 
this file. 


Since most user files are not extremely large, omitting the 
CLUSTERSIZE option when creating the file makes little practical 
difference. Omitting the CLUSTERSIZE option has the effect of assign- 
ing a cluster size equal to the pack cluster size for the disk on 
which the file resides. 


Once a file is opened on an internal I/O channel, all I/O re- 
quests by the BASIC program are handled by means of a read or write 
call from BASIC-PLUS to the Monitor, directed to the nth logical 
block of the file. The RSTS system translates the logical block 
number into a physical block number. This is done by reading the 
list of physical clusters belonging to the file (as kept in the UFD) 
and finding the entry corresponding to the nth logical block. To 
minimize the overhead involved in reading the UFD, which is stored 
on the disk, part of this list of clusters belonging to a file is kept 
in core. This part of the list is called the in-core file window. 
The in-core file window is composed of seven entries from the list 
of file clusters. Since each entry corresponds to one cluster of 
the file, with a file cluster size of one block, 7 blocks (or 1792 
words) of the file are described by the in-core file window. These 
7 blocks can then be read or written without accessing the complete 
list from the UFD stored on the disk. Similarly, with a file cluster 
size of 256 blocks, the in-core file window describes the location of 
1792 blocks of the file or over 459,998 words. This means that when 
performing random access I/O to virtual core arrays and RECORD I/O files, 
any of the 1792 blocks would be read or written without referencing 
the UFD. 


As an example of the use of the CLUSTERSIZE option: 
199 OPEN "MAT-DAT™ FOR UJTPUT AS FILE 14s CLUSTERSIZE 128% 
In this case the file MAT.DAT is created with a cluster size of 128 


blocks. Note that the file is initially 128 blocks long and is ex- 
tended as needed in 128-block increments. 
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Since files with large cluster sizes must be extended by a 
whole cluster at a time and since clusters are always contiguous 
blocks, it may not always be possible to find sufficient contiguous 
free blocks to extend the file. The user should be aware of this 
possibility whenever he creates a file with a cluster size larger 


than the pack cluster size (the minimum cluster size for that disk). 


As another example (typing LINE FEED following FILE 13,): 


190 OPEN "DATA" FOR OUTP:IT AS FILE 12,5 
RECORDSIZE 294825 CLISTERSIZE 4% 


The RECORDSIZE option improves disk throughput when multiple blocks can 
be read or written in a single transfer (see Section 9.2.1). By creat- 
ing the file with a cluster size of 4 (1924 words or 2948 characters per 
cluster) the user guarantees that logical blocks §-3, 4-7, etc. of 

his file are physically contiguous on the disk. 


9.2.3 Formatted ASCII I/O 
BASIC-PLUS permits access to data files by three methods: 


a. Formatted ASCII; 
b. Virtual core arrays, described in Section 9.6; and 


c. RECORD I/O, described in Chapter 11. 


Formatted ASCII data files are the simplest method of data storage, 
involving a logical extension of the PRINT and INPUT statements 
to be used in conjunction with the OPEN statement. 


The formats for INPUT and PRINT statements to be used with the 
OPEN statement are as follows: 


line number INPUT #« expression> ,<list> 


line number PRINT i expreasion> <list> 


where the expression has the same value as the expression in the OPEN 
statement (the internal file designator) and the Zzet is a list of 
variable names, expressions, or constants as explained in the Sections 
describing the PRINT and INPUT statements. 


For example: 


19 OPEN "PR! FOR INIT AS FILE N14 
on INPUT #Ni%s AS 


Line number 1% above causes the paper tape reader to be opened as an 
input source with the internal file designator whose value is con- 
tained in the integer variable N1%. Line number 29 causes input to 
be accepted from logical I/O channel N1%; and the input is associated 
with the variable AS. (N1% must have a value between 1 and 12.) 


9.2.4 File-Structured Vs. Non-File-Structured Devices 


RSTS-11 distinguishes between file-structured (disk, DECtape 
and magtape) devices and non-file-structured (all other) devices. 
When a file is to be found or created on a file-structured device, 
the file specification string in the OPEN statement must include both 
a device designation and a filename. On non-file-structured devices, 
the device name alone identifies a file (filename and extension, if 


specified, are ignored). For example: 


DT@: is insufficient information to specify a file. 

DT@:FRED is sufficient to specify the file FRED on 
DECtape unit @. 

PP: uniquely specifies the high-speed punch. 

PP: FILE specifies a file on the high-speed punch, the 


filename is ignored. 


File specification syntax is such that the default device (the public 
disk storage area) need not be specified. For example: 


DF: QUIZ 
is equivalent to: 


QUIZ 


9.2.5 Opening the User Terminal as an I/O Channel 


The internal file designator (following the # character in the 
INPUT or PRINT statements) is always in the range 1 to 12. File 
designator 9 is, by definition, always open as the user's terminal, 
Internal file designator @ cannot be closed or opened. Use of file 
#2 is indicated below (no OPEN #f% statement is necessary or allowed), 


19 INPUT #5 A$ 


is equivalent to: 


14 INPUT AS 


It is sometimes useful to be able to request keyboard input 
without having the "?" prompting character printed first. This can 
be accomplished by opening the user's terminal ("KB:") on some inter- 
nal file designator other than @. The ? character is only generated 


for input requests on file #@, as shown in the following example: 


LISTNH 

19 OPEN "KBs" AS FILE 1 

2a PRINT “WITH USE OF INTERWAL FILE DESIGNATOR" 

30 PRINT "TYPE YOUR NAMEs FOLLOWED BY RETURN KEY" 
49 INPUT #15 AS$ "THANK YOU" 

54 PRINT: PRINT 

6” PRINT "FOR COMPARISON, WITHOUT FILE DESIGNATOR" 
79 PRINT “TYPE YOUR NAMEs FOLLOWED BY RETURN KEy’* 
8A INPHT AS$s "THANK yor" 

90 END 


READY 


RUNNH 

WITH USE OF INTERNAL FILE DESIGNATOR 
TYPE YOUR NAME, FOLLOWED RY RETURN KEY 
Je Pe JONES 

THANK YO! 


FOR COMPARISON, WITHOUT FILE DESIGNATOR 
TYPE YOUR NAME» FOLLOWED RY RETURN KEY 
? Je Pe JONES 

THANK YO! 

READY 


9.3 OUTPUT TO NON-TERMINAL DEVICES 


In order to direct output to a device other than the user ter- 
minal, the PRINT command is formatted as follows: 


line number PRINT #<expression>,<list> 


where the expression is the internal channel number (the internal 
file designator) of a previously opened output file (see Section 9.2). 
The Zist of information to be output can include any of the output 
information described as applicable to the PRINT statement. For 


example: 


10 OPEN “"DATAL" FOR OUTPUT AS FILE 7% 
2A PRINT #7%5 "START OF DATA FILE" 


The above lines open a file called DATA1 on the disk with internal 
channel number 7 (of 12 possible open files available in the system). 
The first line in that file reads: START OF DATA FILE. 


To output a table of square roots on the line printer, the 

following program could be used: 

LISTNH 

19 LET I%$="LP:" 

28 OPEN I$ FOR O'NTPUT AS FILE 14 

39 PRINT #4145 I5SORCI) FOR T=14 TU 5% 

49 END 

READY 

RINNH 

READY 


The results would appear on the line printer as follows: 


— 


1 
1.4142! 
1,752°GF 
2 
2 23fA7 


Ne wry 


9.4 INPUT FROM NON-TERMINAL DEVICES 


Like the PRINT statement, the INPUT statement can operate upon 


devices other than the user terminal. The form: 


line number INPUT #<expression>,<list> 


causes input to be accepted from the previously opened file or device 
indicated in the expression (see Section 9.2). As long as the value 
of the expression is non-zero, the specified file is read through one 
of the 12 internal I/O channels. If the expression is zero, or 
missing completely, input is from the user terminal. No ? character 
is printed on the terminal when input is requested from a device 
other than the user terminal, opened on file #%. For example: 


19 OPEN “PR:" FOR INPUT AS FILE 3 
23 INPUT #35 AS sBS 


causes the strings A$ and B$ to be read from the high-speed paper 


tape reader. 


Note that the data format is identical to the standard INPUT 
format. If the user wants to read numeric data from a file previously 
created (on disk or DECtape, for example) he should insert commas and 
Carriage returns in the data when he places the data in the file. 


For example: 


199 OPEN "“DTA@:LEN" FOR OUTPUT AS FILE 1% 
114 PRINT #142 A "s" B 5" C 

129 CLOSE 12 

13% OPEN "DT4:sLEN" AS FILE 14 

146 INPUT #1%5 AsBsC 

158 PRINT AsBsC 


is an acceptable sequence to print three values onto a DECtape file, 
read them from that DECtape file, and print the three values on the 
user terminal. As in the example above, once a file is opened it 
can be closed and reopened through the use of a second OPEN state- 
ment. Reopening the file moves the position pointer within the 

file back to the beginning of the file, so that the entire file be- 


comes available again for sequential referencing. 
9.5 CLOSE STATEMENT 
The CLOSE statement is used to terminate I/O between the BASIC 


program and a peripheral device. Once a file has been closed, it can 
be reopened for reading or writing on any internal file designator. 
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All files must be closed before the end of program execution. The 
CLOSE statement causes the output of the last block to an output file. 
Execution of a CHAIN statement automatically closes any open files, 
but does not cause the output of the last blocks to output files. The 
format of the CLOSE statement is as follows: 


zine number CLOSE <expresston> { ,<expression>...} 


The expression indicated has the same value as the expression in the 
OPEN statement and indicates the internal channel number of the file 
to close. Any number of files can be closed with a single CLOSE 
statement; if more than one file is to be closed, the expresstons 

are separated by commas. The CLOSE statement writes the current 
contents of the I/O buffer of an output file to the file before 
closing it and frees core storage space for the program to open other 


files (a maximum of 12 depending upon available space). For example: 


255 CLOSE 234 
345 CLOSE 14a 


Line 255 above closes the files opened on internal I/O channels 2 and 


4. Line 345 closes the file open on internal I/O channel 10. 


The RSTS system detects the character CTRL/Z, ASCII code 26, as 
an end-of-file indicator on formatted ASCII files. The user program 
creating a file is expected to insert a CTRL/Z in a formatted ASCII 
file prior to executing the CLOSE statement. This can be done most 


simply with the statement: 
190A PRINT #NZs CHRSC26)5 


which writes ihe CTRL/Z character into the file opened on channel 
NS. (This end-of-file character need be inserted by the user program 
only into formatted ASCII files.) 


9.6 VIRTUAL DATA STORAGE 


Many applications require a capability to individually address 
and update records on a disk file in a random (non-sequential) 
manner. Other applications may require more core memory for data 
storage than is economically feasible. BASIC-PLUS fills both these 
requirements with a simple random-access file system called virtual 


core. 


The BASIC-PLUS virtual core system provides a mechanism for the 
programmer to specify that a particular data matrix is not to be 
stored in the computer core memory, but within the RSTS-11 disk 
file system instead. Data stored in disk files external to the user 
program remain, even after the user leaves his terminal, and can be 
retrieved by name at a later session, Items within the file are 
individually addressable, as are items within core matrices. In fact, 
it is the similar way in which data are treated in both core and 
random-access files which leads to the name virtual core. 


The matrix format is used to store data because in a normal 
data file, described in Section 9.2.3, the PRINT and INPUT statements 
deal only with the next sequential data element. A normal data file, 
then, is limited in its applications and depends upon a strictly 
sequential treatment of I/O. With virtual data storage, the 
user can reference any element of one or more matrices within 
the file, no matter where in the file that element resides. 
This random access of data allows the user non-sequential 
referencing of the data for use in any BASIC statement. The 
virtual core matrices are read into memory automatically by the 


system. 
9.6.1 Virtual Core DIM Statement 


In order for a matrix of data to exist in virtual core, it 
must be declared in a special form of the DIM statement. This 


Special DIM statement is as follows: 


line number DIM#<integer constant>, <list> 


where the integer constant is between 1 and 12 and corresponds to 
the internal file designator on which the program has opened a disk 
file (see below). The variable list appears as it would in a DIM 
statement for a core-resident matrix. Thus, a 100 by 100 matrix 


could be defined as: 


19 DIM #12%5 AC1AH2100) 


Floating-point constants, integer constants and strings can be 


stored in virtual core matrices. More than one matrix can be speci- 


fied in one virtual core field. For example: 
25 DIM #122 AC1IAAAIs RB&CAAABIs CECA50N) 


allocates space for 1f9@ floating-point numbers, 260% integer 
numbers and 25@@ character strings (16 characters long each). How- 
ever, if a virtual array is defined in this fashion, future refer- 


ences should always dimension the arrays to the same size. 


9.6.2 Virtual Core String Storage 


One of the few differences in data handling between core and 
disk matrices occurs in the storage of strings within string matrices 
in virtual core. Strings in the computer memory are of variable 
length from 9 characters to any arbitrary length. Strings in virtual 
core matrices are of fixed length from @ characters to a specified 
maximum length (all elements of a single string array have the same 
maximum length). This fixed length can be defined by the program and 
varies from 2 characters to 512 characters. The system forces the 
maximum length to be a power of 2; i.e., one of the following lengths: 


2, 4, 8, 16, 32, 64, 128, 256, 512 


Each element in the virtual core string need not use the maximum length 
available, even though space is reserved for each element to be the 
maximum size. If the user indicates other than one of the values above, 


he receives the next higher size. Thus: 


10 DIM #145 XSC1i#> = 65 
is equivalent to: 
19 DIM 41%5 X$€10) = 126 


If no length is specified, a default length of 16 characters is 
assumed. The maximum length of virtual core strings is specified 


as an expression in the DIM statement, using the form: 


line number DIM #<integer constant>,<string (dimenston(s))>=<integer constant 


For example: 


15 DIM #1%5 ASC19B)=32%>5 B$(10%)=4%s C$C199) 
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where: A$ consists of 101 strings of 32 characters each, maximum; 
B$ consists of 101 strings of 4 characters each, maximum; 
C$ consists of 101 strings of 16 characters each, maximum. 


If a length attribute is given in a DIM statement for an in-core 
string matrix, it is ignored, since core storage is allocated dyna- 
mically to hold a string of any length. 


9.6.3 Opening a Virtual Core File 


In order for the user to reference his virtual core file, he must 
first associate a disk file (by name) with an internal channel designator 
from 1 to 12 (which is then used in the virtual DIM declaration). This 
is done with an OPEN, OPEN FOR INPUT, or OPEN FOR OUTPUT statement: 


FOR INPUT 


FOR oureut? AS FILE <expression> 


line number OPEN <string>{ 


where the string is the name of a disk file and the expression speci- 
fies an internal file designator (this is the same format described 


in Section 9.2); thus: 


35 OPEN "ACCT" AS FILE 12 


associates the file named ACCT with internal channel 1. If ACCT 
already exists, then the existing file is used. If there is no file 
named ACCT, one would be created. If the user wishes to destroy an 
old file named ACCT and create a new file of the same name, he can 


use the statement: 


35 OPEN “ACCT FOR OUTPUT AS FILE 12 


which causes the file to be deleted if it already exists and a new file 
created (in which case the file is deleted if not used). If the user 
wants to be alerted that the file ACCT is not present, he could 


write: 
35 OPEN “ACCT FOR INPUT AS FILE 12 


which would cause an error message to be printed if ACCT is not 


found. 
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NOTE 


Virtual core arrays do not permit internal 

buffers larger then 512 characters; there- 

for, the RECORDSIZE option is not used when 
opening a virtual core array file. 


9.6.4 Virtual Core Programming Convention 


Recoverable errors occur when using virtual core if the user 
program does any of the following: 


1. Reference a virtual core array without first opening 
the file. 


2. Reference a non-disk file (for example, DECtape or the 
line printer) as a virtual core array. 


3. Exceed virtual core, that is, define a matrix that is 
bigger than the amount of available disk storage on the 
system. 


It is important to remember that a virtual core file must be 
closed before stopping the program (like any other file). Users are 
urged to read Appendix E which describes the system implementation of 
the virtual core processor. A mastering of this information will 
produce programs which utilize the system resources in an efficient 
manner. 


9.6.5 Programming Example 


As an example of virtual core usage, consider the problem of 
implementing an information retrieval system for a small organization. 
There might be 1000 employees, each needing a 256-character record 
containing the name, home address, home phone, work station and 
phone extension of the employee. Rather than order the records in a 
sequential file, it might be decided to maintain a separate index file 
containing only badge numbers. The sequence of employee records in 
the master file is the same as the badge number sequence in the 
index file. Thus, to extract information on an employee with badge 
n, we find his badge number in the index file and use the index 
found to retrieve his data from the master file. Since the number of 
employees is small, integer data can be used in the badge file; only 
alphanumeric data is stored in the master file. 


oO 
' 


20 


A section of BASIC code which prints an employee's name, given 


his badge number, might appear as follows: 


149 !PROGRAM TO LOOK UP NAMES IN MASTER FILE 


29 OPEN “BADGE” AS FILE 1% !OPEN BADGE FILE 
36 OPEN "MASTER" AS FILE 22 !OPEN MASTER FILE 
40 DIM #145 B2CIABD) 11090 BADGE NUMBERS 
50 DIM #225 ASC1090)=2562 £1000 RECORDS» EACH 
!256 CHARACTERS LONG 
69 INPUT “BADGE NUMBER"SEZ !GET EMPLOYEE NUMBER 
79 GOTO 10% IF BRCIZ)=EZ FOR 1%2=1% TO 10902 {IS BADGE IN FILE? 
82 PRINT "NO SUCH EMPLOYEE": GOTO 60 !NO 
196 !WE NOW HAVE INDEX INTO FILEs 12 {YES 
116 RS=ASCIZ) !BRING RECORD INTO MEMORY 


129 PRINT "NAME IS"$MIDCR$514515)!NAME STORED FROM COLUMN 108 TO 15 


9,7 NAME-AS STATEMENT, FILE PROTECTION AND RENAMING 


The NAME-AS. statement is used to rename and/or assign protection 
codes to a disk or DECtape file, and can only be used on a given file 
by someone logged into the system under the account number which 
owns the file. The format of the statement is as follows: 


line number NAME<estring>AS<string> 


The specified file (the first string indicated) is renamed (as the 
second string indicated). When the file resides on a device other 
than the default device (system disk), the device must be specified 
in the first string and may optionally be specified in the second 
string. No filename extension assumptions are made by NAME-AS; the 
filename extension must be specified in both strings if any exten- 
sion is present in the old filename or desired in the new filename. 
For example: 


75 NAME “DT@:OLDeBAS"” AS "“NEWeBAS" 
is equivalent to: 
75 NAME "DT@:OLD-BAS" as “DT@:NEwW.eBAS" 
but the statement: 
99 NAME “FILE1-BAS" AS "FILES" 
is not advised since FILE2 has no extension and could not subsequently 


be called into core via the OLD or RUN commands (which require 
filename extensions). 


A file protection code can be specified within typed angle 
brackets as part of the second string although it is not required. If 
a new file protection code is specified, it is reflected in the protec> 
tion assigned to the renamed file. If no new protection code is 
specified, the old protection code is retained. See Section 9.1 for 
a complete description of protection codes. 


100 NAME “FILE «EXT" AS "FILE+sEXT<40>" 


changes only the protection code of the file FILE.EXxT stored on the 
system disk. 


290 NAME "DT@:ABC-BAS" AS "XYZ eBAS" 


changes the name of the file ABC.BAS on -DECtape unit g. Since no 
transfer of the file from one device to another can be performed with 
the NAME-AS statement, it is not necessary to mention DTZ: twice; 
that is, the device of the new filename need not be specified. How- 
ever, a diagnostic is generated if a device other than the old device 
is specified. 


120 NAME "NEW" AS “NEW1" 


changes only the name of the disk file NEW. (To transfer a file 
between devices, use the PIP system program described in the RSTS-11 
System User's Guide.) 


9.8 KILL STATEMENT 

The KILL statement is of the form: 

Line number KILL <string> 

and causes the file named string to be deleted from the user's file 
area. (The file can no longer be opened, but if it is already open 
the file remains available until it is closed.) For example, when 
the user has completed all work with the file XYZ (note that the 
filename has no extension) on the system disk, he could remove the 


file from storage by executing the following statement: 


455 KILL "xyz" 


9-22 


A user is not allowed to KILL a file that is write-protected 
against him. (He must use the NAME-AS statement to change its pro- 


tection first.) 


The KILL (and NAME-AS) statement can be issued in immediate 
mode. It should be noted that KILL is more general than UNSAVE, 
which is primarily used to delete source (.BAS) files (see the RSTS-11 
System User's Guide). KILL can be used to delete any file, including 
a file with a null extension (which the UNSAVE command cannot delete). 


9.9 CHAIN STATEMENT 


If a user program is too large to be loaded into core and run 
in one operation, the user can segment the program into two or more 
separate programs. Such programs are called into core for execution 
by means of a CHAIN statement. Each program section is assigned a 
name and control can be transferred between any two programs. A 
CHAIN statement is of the form: 


line number CHAIN <string> {<line number>} 


and causes the program named by the string to be called, compiled 

(if necessary), and executed. The Zine number, if specified, desig- 
nates the line at which the program is to be started. If the line 
number is omitted, the program is started at the lowest numbered 
line (as though a RUN command had been used). The CHAIN statement 

is the last statement executed in each program segment other than the 
last segment. For example: 


1980 CHAIN "MAIN.eBAC™ 2000 
causes the program MAIN.BAC to be loaded and started at line 2999. 
Chaining to precompiled program files (.BAC files) is consid- 
erably more efficient than chaining to BASIC source program files 


since .BAS files require compilation upon each call. 


Communication between chained programs is performed by means of 


the user's file area. 


When the CHAIN statement is executed, all open files for the 
current program are closed, the new program segment is loaded, and 
execution continues. Any files to be used in common by several pro- 


grams should be opened in each program. 
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CHAPTER 10 


BASIC-PLUS INPUT AND OUTPUT OPERATIONS 


10.1 READ AND DATA STATEMENTS 


A READ statement is used to assign to a list of variables values 
obtained from a data pool composed of one or more DATA statements. 


The two statements are of the form: 


line number READ <list of variables> 


tine number DATA <list of values> 


The list of variables can include floating point, integer, subscripted, 
or character string variables. The list of values must correspond in 
type with the variables to which the value will be assigned (the ex- 
ception is that integer and floating point values are interchangeable, 


although they are stored according to the type of the variable). 


The data pool consists of all DATA statements in a program. 
Values are read starting with the DATA statement having the lowest 
line number and continuing to the next higher, etc. The location of 
DATA statements in a program is irrelevant, although for simplicity 
they are usually kept together toward the end of the program. (The 
DATA statements must occur in the proper numeric sequence, however.) 
A DATA statement must be the only statement on a line, although a 
READ statement can occur anywhere on a line. Comments are not per- 
mitted at the end of a DATA statement. 


If a READ statement is unable to obtain further data from the 
data pool, an error message is printed and program execution is ter- 
minated. (This error can be treated through the ON ERROR GOTO state- 


ment, Section 8.4.) 


Quotes are necessary in DATA statements only around string items 
which contain a comma or where leading, trailing or embedded blanks 
within the string are significant. The data pool, composed of values 
from the program's DATA statements, is stored internally as an ASCII 
string list. When a numeric variable is read, the appropriate ASCII 
to numeric conversions are performed. When a string variable is 


read, the string is used as it appears in the DATA statement. If 
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the item did not appear in quotes; leading, trailing, and embedded 
spaces are ignored. If the item did appear in quotes, the string 


variable is equated to the entire string within the quotes. 


Matrices are read from DATA statements via the MAT READ statement 
of the form: 


line number MAT READ <matriz> 


This reads the value of each element of a predimensioned matrix from 
the data pool. Each element in the list of matrices indicates the 
maximum dimension of the matrix to be read (which cannot be greater 
than the dimensioned size of the matrix). Individual elements are 


separated by commas. For example: 


19 DIM AC20s20)sBC59) 
20 MAT READ A 
30 MAT READ 3(35) 


The above lines read values for the 20 x 20 matrix A and 35 out of 
the possible 50 values for the B matrix (remaining elements are zero). 
Data is read in row by row; that is, the second subscript varies most 


rapidly. 


10.2 RESTORE STATEMENT 


The RESTORE statement reinitializes the data pool of the program's 
DATA statements. This makes it possible to recycle through the DATA 
statements beginning with the lowest numbered DATA statement. The 
RESTORE statement is of the form: 


line number RESTORE 
For example: 
865 RESTORE 
causes the next READ statement following line 85 to begin reading data 
from the first DATA statement in the program, regardless of where the 
last data value was found. See Section 3.3.1 for an example program 


using the RESTORE statement. 


The RESTORE statement can be placed in any position on a multiple 
statement line. 
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10.3 INPUT STATEMENT 


The INPUT statement allows data to be entered to a running pro- 
gram from an external device, the user's keyboard, disk, DECtape, 
paper tape reader, etc. The full form for this statement is: 


line number INPUT {#<expression>,} <vartable list> 
In many cases the simpler form: 
line number INPUT <variable list> 


is used. This last form causes a ? to be printed at the terminal 
and the system then waits for the user to respond with the appropri-~ 
ate values. If sufficient values are not typed, the system prints 
another ?; if too many values are typed, excess values are ignored. 
This last form also allows the user to insert strings to be printed 
between the variables to be input. For example: 


19 INPUT "YOUR NAME IS"$NSs*ACCOUNT NUMBER"3A3"THANK YOU" 


when executed would allow the following interaction at the terminal 


(the underlined characters are typed by the user): 


YOUR NAME IS? JEAN 
ACCOUNT NUMBER? 473 
THANK YOU 


The format: 
line number INPUT #<expression>, <variable list> 


causes input to be read from the file or device indicated, in the ex- 
pression, by the internal file designation number given when the file 
was opened. (See Section 9.2 for a description of the OPEN 
statement.) If the value of the expression is non-zero and the 
specified file is open to the user terminal as an input device, then 
no ? character is printed at the terminal when input is requested. 


For example: 


75 OPEN "KBs** FOR INPUT AS FILE e2 
6A INPUT #2548 
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The system then pauses while the user types a numeric value for the 
variable A, although no prompting ? or character string message is 
printed on the terminal. 


Another format of the INPUT statement allows for the entering 
of an entire line of data as a single character string entity, re- 
gardless of embedded spaces or punctuation. This is different from 
the normal mode of string input, where the comma, apostrophe, single 
quote and double quote characters have special significance. The 
format is: 


line number INPUT LINE{#<expresston>, }<string vartable> 
For example: 


25 INPUT LINE AS 


would pause and allow the user to enter a line followed by the 
RETURN, LINE FEED or ESCAPE key (see also Section 5.3). The end of 
the line being input is the carriage return/line feed sequence (or 
line feed/carriage return/null or ESCAPE, see Section 5.3) which is 
appended to the data typed by the user. As another example: 


20 OPEN “F2-DAT" FOR INPUT AS FILE 7 
25 INPUT LINE #7s BS 


These lines cause the system to open a file F2 on the system disk on 
channel 7 (of 12 possible channels) to input a line of characters 
up to the next LINE FEED character. (See Table 9-4 for the size of 


buffers available for each device.) 


The MAT INPUT statement is used to input the values of a predi- 
mensioned matrix from a specified input device. Where no device is 


specified, the input is accepted from the user terminal. For example: 


200 MAT INPUT AC2%) 


causes 20 floating-point values to be accepted as elements of the 


matrix A. A statement of the form: 
line number MAT INPUT{#<expression>, }<vartable list> 


causes the input to be read from a file or device previously opened 
on the internal channel indicated by the expression. 
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45 DIM BC16525) 
50 OPEN "DT1:DATA1" FOR INPUT AS FILE 1 
55 MAT INPUT #1» BC149,25) 


The above lines cause the file DATA1 on DECtape 1 to be opened for 
input on channel 1 (of 12 possible channels) and a matrix of values 
for the elements of B to be read to fill B(10,25). The zero elements 
are not assigned a value. When input is from the user terminal, 

is printed; however, reference to another device does not cause the 
printing of the prompting character. Depending upon the name of the 
matrix, the MAT INPUT statement allows input of floating-point, inte- 


ger, or character string values. 


10.4 PRINT STATEMENT 


In its simplest form, the PRINT statement: 
line numLer PRINT 


causes a carriage return/line feed to be performed on the user ter- 


minal. The format: 
line number PRINT <itst> 


causes the printing of the elements in the list on the user terminal. 
An element in the list can be any legal expression. When an element 
is not a simple variable or constant, the expression is evaluated 
before a value is printed. The list can also contain character 
strings between quotes which are printed exactly as typed between 


quotes. 
NOTE 


If a character string is enclosed in a PRINT state- 

ment with an initial quote and no terminating quote, 
a terminating quote is considered to follow the last 
character of that PRINT statement. For example: 


10 PRINT "NAME IS A$ 


16 PRINT "NAME IS Ags" 
20 PRINT "NAME IS" AS 


Line 19 is shown in two equivalent forms. Line 29 is 
the correct form to generate the printed line: 


NAME IS JOHN DOF 


where AS = "JOHN DOE". 
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Elements in the list are separated by commas or semicolons. For 


example: 


19 A=ls: Bees: C=3 
15 PRINT A$ A+B+Cs» CrAs “END! 


when executed causes the following line to be printed: 


1 6 2 END 


A terminal line is considered to be divided into five! print zones of 
fourteen spaces each. Use of these zones involves the comma character 
which causes the print head to move to the next available print zone 
(from 1 to 14 spaces away). If the fifth print zone on a line is 


filled, the print head moves to the first print zone on the next line. 
The semicolon character functions as follows: 


a. if an integer or floating-point variable, function, or expres- 
sion is followed by a semicolon, the value is printed with a 
preceding minus sign if the number is negative, or a preced-~ 
ing space if it is positive. The number is then followed by 
a Single space. 


b. character strings and string variables followed by a semi- 
colon are printed with no preceding or trailing spaces. 


Any PRINT statement which does not end with a semicolon or comma 
character causes a skip to the next line after printing the elements 

in the list. The presence of the punctuation character at the end of 
the PRINT list causes the next PRINT statement to continue on the 


line under the conditions already defined. 
In general, the output rules for the PRINT statement are: 


a. suppression of leading and trailing zeros to the right 
of a decimal point. Where a number can be represented 
as an integer, printing of the decimal point is also 
suppressed. 


b. at most six significant digits are printed. 


c. most numbers are printed in decimal format. Numbers 
too large or too small to be printed in decimal format 
are printed in exponential format. 


ad. character string constants are printed without leading 
or trailing spaces. 


IThe actual number of print zones is INT (n/14), where n is the size 
of the print line. 
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e. extra commas cause print zones to be skipped. 


f. semicolons separating character string constants from 
other list items are optional; omitting punctuation has 
no effect on the output format in this case, 


Output can be directed to a device other than the user terminal 
with the following command: 


line number PRINT #<expression>, <list> 


Where the expression is the number of a previously opened output file, 
out of 12 possible open files (see Section 9.2). For example: 


10 OPEN “PP:" FOR OUTPUT AS FILE 3 
50 PRINT #35 BsDsA+7sFNXCB) 


causes four values to be punched onto paper tape by the high speed 
punch which is opened for output as file 3, of 12 possible files. 


10.4.1 PRINT-USING Statement 


In order to perform formatted output, the following statement 
is used: 


line number PRINT{#<expression>, }USING <string>,<list> 


where the expression (which is optional) indicates the file or device 
which is the destination of the output; the string is either a string 
constant, string variable, or string expression which is an exact image 
of the line to be printed; and the list is a list of items to be printed. 
All characters in the string are printed as they appear except for the 
Special formatting characters and character combinations described on 
the following pages. The string, or portions of the string, are re- 
peated until the Zist is exhausted. The string is constructed accord- 
ing to the following rules: 


Exclamation Point 


An exclamation point identifies a one character string field. 
The string is specified in the <list> within the PRINT statement. 
For example: 


19 PRINT USING "HHI", “Ant, eCDH, wEPE 
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which causes: 
ACE 


to be printed at the user's terminal. The first character from 
eaoh of the three string constants or variables is printed. Any 
other characters beyond the first are ignored. 


String Field 


A variable string field of two or more characters is indicated 
by spaces enclosed between backslashes. The backslash character 
(\) is produced by typing SHIFT/L on the Teletype keyboard. En- 
closing no spaces indicates a field two columns wide, one space is 


equivalent to a field three columns wide, etc. For example: 
20 PRINT USING “\\\ ANNs "ABCD". “EFGHI" 


causes 


ABEFGH 


to be printed at the user's terminal. The first two backslashes 
have no spaces enclosed, hence permit the printing of two charac- 
ters (AB). The second two backslashes enclose two spaces and 
permit the printing of four characters (EFGH). No spaces are 
printed unless specifically planned. 


Numeric Field 
Numeric fields are indicated with the # character. Any decimal 
point arrangement can be specified and rounding is performed as 
necessary (not truncation). For example: 
30 PRINT USING "“###o##™", 122345 


causes 


12-35 


10-8 


to be printed on the user's terminal, while 


40 PRINT USING "####"%s 126345 
58 PRINT USING "####.",120345 
60 PRINT USING "“##"5, 1300 


causes 


12 
126 
% 186 


to be printed on the user's terminal. Numeric fields are right justi- 
fied; that is, if a number does not fill the allotted space, leading 
blanks precede the number. When the field specified is too small 

for a constant or variable to be printed, the % character is printed 
to indicate the error. The number is then printed. 


If the format field specifies a digit as preceding the decimal 
point, at least one digit is always output before the decimal point. 
If necessary, that digit is zero. 


Asterisks 


If a number field designation begins with **, any unused spaces 
in the number are filled with asterisks, For example: 


16 A=27-95:3 BH=107-503 C=1987-59 
20 PRINT USING “xe##e##"> As BoC 


prints the following: 


**¥27 295 
*107-58 
1097-56 


Notice that the ** characters act as two additional # characters 
as well as allowing asterisk fill. 


Exponential format (see below) cannot be used in a field with 


leading asterisks. Negative numbers cannot be output using asterisk 
fill unless the sign is output following the number (see below). 
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Exponential Format 


When the exponential form of a number is desired, the numeric 
field is followed by the string tttt (four + characters) which 
allocates space for E-xx. Any arrangement of decimal points is 
permitted. For example: 


5 FSa"sattttHeee eee 
10 A=1A000. 
206 PRINT USING FS sAsA 


causes 
1BE 63 10900 
to be printed at the user's terminal. 
All format positions are used to output a number with an expo- 


nent. The significant digits are left justified and the exponent is 
adjusted. 


Trailing Minus Sign 


If a number field designation is terminated with a minus sign, 
the sign of the output number is printed following the number, 
rather than preceding it. A blank is printed to indicate a positive 
number. 


19 A=-19-5 
20 PRINT USING “##.##- #### 0##%s Asf 


which prints: 
18-«56- -10250 
Note that if the trailing minus is not used, space must be re- 


served in the number field designation for the sign to precede the 
number. 
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Dollar Signs 


If a number field designation begins with $$, a dollar sign 
immediately precedes the first digit of the number: 


16 A=77-44: B=304.55: C=2211.-49 
20 PRINT USING "$$##-##", AsBsC 


which prints: 


$77 +44 
$304655 


% 221164 (insufficient space to print C along with $ 
character) 


Note that the $$ characters provide for the printing of two addition- 
al characters in the number. Since one character is a $, the effect 
is to allow for one additional # designation beyond the ones typed 
by the user. 


Exponential format (see above) cannot be used in a field with 
leading dollar signs. Negative numbers cannot be output using the 
floating dollar character unless the sign is output following the 
number (see above). 


Commas 

If one or more commas appear to the left of the decimal point 
(if any) in a number field designation, then commas are inserted 
every three digits to the left of the decimal point. A comma to 
the right of the decimal point is considered a printing character. 
For example: 

10 PRINT USING “#s###H HH oH HAFH OHH") 12345059123 245651 
prints the following: 
12534558 123.551 


Insufficient Format 


If insufficient format characters are present in a field when 
a number is output, a % character is printed in the first position 
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of the field followed by the number in standard format, usually 
causing the field to be widened to the right. The user is 
guaranteed his entire number. For example: 


1@ PRINT USING "##e## ##-.##%5 1263453 -1205 


prints the following: 


12235 4-125 


Rounding occurs when digits are dropped at the right of numbers. If 
rounding causes the number to exceed the format allowed, the % char- 
acter is used. For example: 


10 PRINT USING "“e## o##", 01255 0999 
prints the following: 


013 % 0999 


Format Too Large 


If a numeric field specification results in an attempt to 
output more significant digits than are available for the number, 
zeros are substituted for all digits following the last significant 
digit. Six significant digits are available with the 2-word, 
single precision math package and fifteen digits with the 4-word, 
double precision math package. 


PRINT Statement Punctuation 


wWnen the PRINT-USING statement is used, the usual PRINT state- 
ment punctuation characters (commas and semicolons) have no effect 
on the output format, except that a semicolon at the end of the 
PRINT list does inhibit termination of the printed line. 


16 PRINT USING "#4 #8 #8" 5 15253 


prints the following: 
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As another example: 


18 PRINT USING "#.8", 2-53 
26 PRINT "x" 


prints 


2e59X 


fs another example: 


10 LET 4=1-32111: B=2.45457 

15 LET F$ =" A=##.## Beas#segen 
26 OPEN "LPs" FOR OUTPUT AS FILE 4 
25 PRINT #4, USING FSs AsB 


would cause: 


Az 1,32 Re 2,45 
to be printed on the line printer. 


10.4.2 MAT PRINT Statement 


The MAT PRINT statement allows for easy printing of a predimen- 


sioned matrix. The statement is of the form: 


line number MAT PRINT {#<expression>, }<matriz> 


for example: 


15 DIM AC16) 
25 MAT PRINT AC15) 


If the specified matrix name is unsubscripted, the entire matrix is 
printed. If the matrix specification is subscripted, the subscript(s) 


indicates the maximum size of the matrix to be printed, 


The matrix name can be followed by a semicolon to indicate that 
the values are to be printed in a packed fashion, or by a comma to 
indicate that each element is printed in its own zone. For example: 


18 DIM AC1@519)5BC10520) 
20 OPEN “LP: FOR OUTPUT AS FILE } 


120 MAT PRINT #15 A$ !PRINT MATRIX A IN PACKED FORMAT 
130 MAT PRINT #15 BC10,10)>5 !14*1@ MATRIX IS PRINTED, 
15 VALUES PER LINE 
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Row and column matrices can also be printed. For example: 


19 DIM AC5)s BCIA) 
aa OPEN “"LP:"* FOR OJTPUT AS FILE } 
30 MAT PRINT #12 A; !PRINT UN ONE LINF ON CHANNEL 1 


4@ MAT PRINT #1> B tPRINT IN COLUMN FORMAT UN 
!CHANNEL 1 


Line 3% causes A to be printed as a row matrix, closely packed; line 


4f causes B to be printed as a column matrix. The form: 


709 MAT PRINT A> 


would cause the matrix A to be printed as a row matrix, five values 


per line (at the user terminal). 


10.4.3 PRINT Functions 


In order to aid in formatting simple and complex PRINT statements 


the following functions are provided: 


Function Meaning 


POS (X) Returns the current position on the output 
line; where X is the I/O channel number. 
POS(#) returns the value for the user's 
terminal. 


TAB (X) Tab to position X in the print record. For 
example, a standard Teletype has 72 printable 
columns numbered @ through 71. TAB(4) causes 
sufficient spaces to be output to move the print 
head to column 4. If the print head is currently 
past position 4, no spaces are output. 


For example: 
14 PRINT "xX" STARCIA)3PO0S(9) 


causes the following to be printed: 


Xx 10 
av A 


position 1 position 19g 
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CHAPTER 11 


RECORD I/O 


There are three methods of performing I/O in BASIC-PLUS. For- 
matted ASCII I/O is simple and flexible, but requires conversion of 
numbers by the system from an internal form to an externally usable 
ASCII representation and does not permit random access to files. 

I/O to virtual core arrays permits high-speed random access to files 
but can be used only on disk files and does not allow true intermixing 
of string and numeric elements or use of the RECORDSIZE specification. 


The third type of I/0, Record I/O, permits the user program to 
have complete control of I/O operations. Properly used, Record I/O 
is the most flexible and efficient technique of data transfer avail- 
able under BASIC-PLUS. These advantages are obtained at the cost 
of the simplicity of the formatted ASCII and virtual array I/O. Less 
experienced users should first experiment with the simpler I/O tech- 
niques before attempting Record I/O. 


Record I/O is an optional feature not available on all RSTS-11 
systems. If Record I/O is not present on a system, any attempt to 
use it results in an error message. 


11.1 OPENING A RECORD I/O FILE 


To open a file for Record I/O requires: an OPEN statement, 
described in Section 9.2. One additional field has been added to 
the OPEN statement, the MODE field. The complete format of the 
OPEN statement is as follows: 


(FOR INPUT } 
FOR OUTPUT 


{,RECORDSIZE <expr>} {,CLUSTERSIZE <eaxpr>} {,MODE <expr>} 


line number OPEN <string> AS FILE <expr> 


The MODE option is used to establish device-~dependent properties of 
the file. For disk files MODE indicates that the file is to be 
opened in UPDATE mode (see Section 12.2 ). For non-file structured 
magtape operations, MODE establishes the density and parity set- 
tings for the magtape (see Section 12.3.6). For line printer opera- 
tion, MODE is used in conjunction with the optional forms control 

to establish the current form length (see Section 12.5.2). On all 
other devices the MODE option has no effect. 
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The RECORDSIZE and CLUSTERSIZE options can be specified for 
Record I/O files as described in Sections 9.2.1. and 9.2.2. 


11.2 CLOSING A RECORD I/O FILE 


Every Record I/O file must be closed once I/O operations 
on that file are completed. Files are closed with the CLOSE 
statement, as described in Section 9.5. The CLOSE statement 


is of the form: 
line number CLOSE <expr>{,<expr>...} 


where the value of the expression(s) specifies one of the twelve I/0 


channels. 


Two cautions apply to closing Record I/O files. First, the 
CLOSE statement for formatted ASCII and virtual array files causes 
the final record of the file to be written before closing the file. 
However, all I/O to Record I/O files is explicitly performed (with 
GET and PUT statements). The user program must ensure that the 
last record is explicitly written onto a Record I/O file. 


Second, if a Record I/O file is later to be read as a formatted 
ASCII file, the user program must insert a CTRL/Z which is a CHR$ (26) 
following the last character in the file. CTRL/Z is required as 
the end-of-file character for formatted ASCII files. The CTRL/Z 
need not be inserted into any file which is not to be read as a 
formatted ASCII file. 


11.3 THE GET AND PUT STATEMENTS 


Input and output to Record I/O files is performed directly 
between the device channel and the I/O buffer created by the OPEN 
statement. All I/O is specified in terms of single records, using 
the GET and PUT statements. GET and PUT are of the form: 


line number GET #<expri> {,RECORD <expr2>} 


line number PUT #<expr1> {,RECORD <expr2>} {,COUNT <expr3>} 


If the RECORD option (see Section 11.3.3) is not used, the GET 
statement reads the next sequential record from the file open on the 
channel designated by <expr1>. The record is placed in the I/O buffer 
which was associated with the channel by the OPEN statement. The size 
of the record depends upon the characteristics of the device on which 
the file resides, as described in Table 11-1. 
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Table 11-1 
Device Record Characteristics 


Device Input Record Characteristics 


disk Records (sometimes called blocks or segments) are 
always 512 characters long. When the RECORDSIZE 
option is specified in the OPEN statement, and a 
buffer longer than 512 characters is created, the 
system reads as many full records as possible. If 
several disk records are read with a single GET 
statement, the next sequential record is that 
record immediately following the last record read. 


DECtape Records are always 510 characters long. The 
RECORDSIZE option has no effect on DECtape I/O. 


When performing file-structured I/0, magtape rec- 
ords are always 512 characters. With non-file 
structured I/0, magtape records can be of any 
length; only one record can be read per GET state- 
ment; and the record length cannot exceed the buf- 
fer size as determined by the RECORDSIZE option. 


magtape 


keyboard The GET statement obtains one line from the key- 
board, up to the first line delimiter (CTRL/Z,RETURN, 


LINE FEED or ESCAPE). 


A record consists of a single card. The RECORD- 
SIZE option has no effect on card reader input. 


card reader 


RSTS-11 reads a full buffer of input from the 
paper tape reader unless an end-of-tape is de- 
tected. 


paper tape 


Similarly, if the RECORD and COUNT (see Section 11.3.2) options 
are not used, the PUT statement writes the contents of the I/O buffer 


for the specified. I/O channel onto the next sequential record of the 
file. The expression <exprl> specifies the internal channel number 

on which the file was opened. PUT writes a single record on the 
device, with the exception of disk files which permit several records 
to be written at a single time (using the RECORDSIZE option to increase 
I/O buffer size). 


11.3.1 The RECOUNT Variable 


Non-file structured devices, as can be seen in the description 
of the GET statement, can read less than a full buffer of data. 
To permit the program to determine how much data was actually read, 
a system variable, RECOUNT, contains the number of characters read 
following every input operation. 


RECOUNT is used primarily for non-file structured input; how- 
ever, it may also be used with file-structured devices. On file- 
structured DECtape and magtape input, RECOUNT is set to the standard 
record length (510 characters for DECtape and 512 characters for 
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Magtape). On disk file input, RECOUNT is set to the RECORDSIZE or 
the next lower multiple of 512 if the RECORDSIZE is not an even 
multiple of 512. 


RECOUNT is set by every input operation on any channel (includ- 
ing channel g). It is, therefore, essential that the RECOUNT value 
be tested immediately following the GET statement. 


11.3.2 The COUNT Option 


The COUNT option used in a PUT statement with a non-file 
structured device specifies the number of characters to write in 
the current record. However, the COUNT expression cannot be 
greater than the size of the I/O buffer. 


For example, where internal channel 1 is opened as magtape 
unit @ (non-file structured magtape), the following statement could 


be used to write an 80-character record: 


199 PUT #1%,COUNT 80% 


For files on file-structured devices (disk and DECtape) the COUNT 
option is ignored. 


11.3.3 The RECORD Option 


With disk files, the user has the capability of performing 
random access I/O to any record of the file. Records in a disk 
file are always 512 characters long and are logically numbered 
within the file from 1 to n, where n is the size of the file. 


The RECORD expression provides the logical record number of 
the file to GET or PUT. For example, assuming a disk file opened 
on internal channel 1, the following statement writes the contents 
of the I/O buffer associated with channel 1 on records 1g through 
99 of that disk file: 


260 PUT #1%5s RECORD I% FOR 1%4=10% TO 99% 
More than one record can be read or written by assigning a large 
I/O buffer to the file with the RECORDSIZE option in the OPEN 


statement. (The size of the buffer does not affect the numbering 
of the records within the file.) 
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If the disk file on channel 1 were opened with a RECORDSIZE of 
1924 characters (which would cause two 512-character records to be 
written with each PUT) the PUT statement would be written as follows: 


200 PUT #1%5 RECORD 1% FOR I%=14% TO 98% STEP 2% 


After performing a random access GET or PUT on a disk file, the 
next GET or PUT statement on that channel accesses the next sequen- 
tial record if no RECORD. number is specified. For example: 

2906 OPEN "DATA" AS FILE 1%s RECORDSIZE 512% 


30% GET #1%5 RECORD 99% 
316 PUT #12 


The PUT statement at line 319 writes record 19f@ of the disk file. 
11.4 WORKING WITH RECORD I/O FILES 


Techniques for opening, closing, reading and writing record 
I/O files have been described. Techniques for moving data into or 
out of the file are provided by extensions to the BASIC language 
permitting the program to access, as characters, and modify the con- 
tents of the I/O buffer associated with an internal channel. This 
is accomplished by means of the FIELD, LSET, and RSET statements. 


11.4.1 The FIELD Statement 


The FIELD statement is used to dynamically associate string names 
with all or part of an I/O buffer. The FIELD statement has the form: 


line number FIELD #<expr>, <expr1> AS <stringvari1> 


{,<expr2> AS <stringvar2>...} 


where <expr> is an internal channel number associated with some file 
by an OPEN statement; <expri> is the length, in characters, of the 
associated string variable; and <stringvar1> is a unique string vari- 
able name. The names are associated from left to right with suc- 
cessive characters in the I/O buffer assigned to the designated in- 
ternal channel number. For example: 


75 FIELD #225 18% AS ASs 20% AS Bs 3% AS FS 


Statement 75 associates three strings, AS, BS, and F$ in the I/O 
buffer, with lengths of 10, 20, and 3 characters, respectively. The 
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total number of characters represented in this statement is 33. 
The total number of characters must be less than or equal to the 
actual I/O buffer size (which is dependent on the device and the 
RECORDSIZE option, as described in Section 9.2.1). 


FIELD statements do not move data but rather permit direct 
access to sections of the I/O buffer via string variables. The 
effect upon a string variable is temporary and is nullified by any 
attempt to assign a value to the variable (other than with LSET 
and RSET, described in Section 11.4.2). For example: 


109 OPEN "FILE" AS FILE 22% 
110 FIELD #2%5 5% AS AS 
129 LET AS = “ABCDE"* 


Line 128 causes the string variable A$ to be removed from the I/O 
buffer. The string ABCDE is not stored in the I/O buffer by line 129. 


A FIELD statement is an executable statement, rather than a 
Compiler directive (such as a DIM statement). To illustrate: 
suppose that each record of a disk file contains sixteen 32-character 
sub-records and that each sub-record consists of one 5-character 
field and one 27-character field. In order to extract the eighth sub- 
record from the I/O buffer, the following statement could be executed: 


299 FIELD #125 224% AS D$s 5% AS BSs 274 AS AS 


Line 200 causes the string variables B$ and A$ to point to the 
desired sub-record. The string D$ is created to permit the first 
seven sub-records to be skipped. An even more general statement 
could be used to obtain any of the sub-records in the I/O buffer, 
as follows: 


299 FIELD #125 (€1%2-12)*32% AS DS» 5% AS BSs 274% AS A> 


When the statement above is executed, I% should contain the number 
of the sub-record that BS and AS are to contain, as an integer from 
1 to 16. 


Subscripted string variables can also be used in FIELD state- 
ments. For example, the following statements could be used to al- 
locate the sub-records, described in the previous example, to two 
string arrays: 
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398 DIM A$C15)s5 BSC15) 

310 FOR I% = @% TO 152 

329 FIELD #125 12*32% AS DS» 5% AS BSCIZ)s 27% AS ASCIZ) 
334 NEXT 12 


With each iteration of the FIELD statement at line 320 the dummy 
string D$ increases by 32 characters, making the displacement from 
the start of the I/O buffer to the string B$(I%) equal to 32 times 
I% characters. Once this loop is executed, the position of each 
string in the arrays A$ and B$ is fixed, A$(@) and B$(f) pointing 
to the first sub-record and A$(15) and B$(15) to the last. 


However, virtual array strings must not be defined as string 
variables in a FIELD statement. When strings are defined as virtual 
arrays they are required to be in a fixed place in both a disk file 
and the I/O buffer for that file. Attempting to specify a virtual 
array string variable in a FIELD statement will have no effect on 
the virtual array string. 


11.4.2 LSET and RSET Statements 


Once the strings have been defined as part of the I/O buffer 
by a FIELD statement, it is necessary to be able to store values 
in these strings without moving them from the I/O buffer. The 
LSET and RSET statements store values in a string without redefin- 
ing the string position. These statements are of the form: 


line number LSET <stringvar> {,<stringvar>...} <string> 


line number RSET <stringvar> {,<stringvar>...} <string> 

where <stringvar> represents any legal string variable name (multiple 
string variable names can be separated by commas) and <string> repre- 
sents any legal string expression. 


LSET and RSET store the value of the string expression into 
the designated string or strings. The string previously stored in 
the variable is overwritten. The length of the string is not 
changed; if the new string is longer than the existing string, the 
new value is truncated. If the new string is shorter than the 
existing string, it is either padded with spaces on the right by 
LSET or padded with spaces on the left with RSET. LSET, then, 
causes the string to be left-justified in the field and RSET 
causes the string to be right-justified. 
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The normal use of LSET and RSET, as described in this Section, 
is to store data in strings allocated within an I/O buffer by a 
FIELD statement. LSET and RSET can be used to assign a value to 
any string variable within a BASIC-PLUS program. 


11.4.3 Notes on the Use of the LET Statement 


The LET statement cannot be used to place string values into 
an I/O buffer as it causes the string to be redefined elsewhere. 
Another restriction on LET occurs when that statement is used to 


equate two strings, as follows: 


53 LET AS=BS 


To avoid unnecessary character manipulation, this operation causes 
AS and B$ to reference the same string. Normally, any operation 
which alters B$ causes that string to be moved, so no conflict 
arises. However, LSET and RSET do not move strings; they alter 


existing strings in a fixed position. 


Therefore, if the value of BS in line 50 above were altered 
by an LSET or RSET statement, the value of A$ also changes. For 
example: 


409 BS ="ABC" 
4106 AS = BS 
429 LSET BS = "XYZ" 


Both A$ and B$ contain "XYZ" following the execution of line 429. 


This phenomenon has another ramification; if the string B$ 
in this example had been defined by a FIELD statement as being 
in some I/O buffer, the string A$ would also be in the I/O buffer 
(being identical to BS). Executing a GET statement to read another 
record into the I/O buffer would then change the value of AS as 
well as BS. 


When it is not desirable for the strings A$ and BS to be physi- 
cally identical, there is a means of causing the string BS to be 


moved into the string A$. This operation is performed as follows: 


30% LET AS = BSt"" 
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foe) 


Line number 3$@ appends a null string to BS, which has no effect on the 
string AS but causes the two strings to occupy different storage areas. 


11.5 CVT CONVERSION FUNCTIONS 


The FIELD, LSET, and RSET statements allow a program to store or 
retrieve string data directly from an I/O buffer. In order to permit 
floating-point and integer values in Record I/O files, four conversion 


functions are provided as described in Table 11-2. 


Table 11-2 
CVT Conversion Functions 


Function Form 


CVTSS (1%) Maps an integer into a 2-character string. 


CVTS% (AS) maps the first two characters of a string 
into an integer. If the string has fewer 
than two characters, null characters are 
appended as required. 


CVTFS (X) maps a floating-point number into a 4- or 
8-character string (depending upon whether 
the 2-word or 4-word math package, 
respectively, is being used on the system). 


CVTSF (AS) maps the first four or eight characters 
(depending upon whether the 2-word or 
4~word math package, respectively, is being 
used on the system) of a string into a 
floating-point number. If the string has 
fewer than the required number of characters, 
null characters are appended. 


These functions do not affect the value of the data, but rather its 
storage format. Each character in a string requires one byte of 
storage ( 8 bits); hence, characters may assume (decimal) values from 
@ through 255 and no others. A 16-bit quantity can be defined as 
either an integer or a 2-character string; 2-word floating point 


numbers can equally be defined as 4-character strings. 


The CVT functions perform two important functions: first, they 
permit dense packing of data in records. For example, any integer 
value between -32768 and 32767 can be packed in a record in two char- 
acters using CVT%$; this would only be true for integers between -9 
and 99 if the data were stored as ASCII characters. Second, converting 
the internal numeric representation to an ASCII string (as with the 
NUM$ function) is a more time-consuming process than that performed 
by the CVT functions. Thus, the CVT functions provide the means to 


speed the processing of a large amount of data within a file. 
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11.6 EXAMPLES OF RECORD I/O USAGE 


LISTNH 

10 OPEN "KB:" FOR OUTPUT AS FILE 1 

20 FIELD #15 10 AS A$s 19 AS BS» 10 AS CS 
306 LSET A$="12345" 

49 RSET BS$="67893" 


50 RSET C&S="VWXYZ" 
63 PUT #1. COUNT 30 
ga END 


READY 


Figure 11-1 
Record I/O Example #1 


In Figure 11-1, the device KB: is opened with the default size 
(128 characters) buffer length by the OPEN statement at line 19. 
The FIELD statement at line 2@ defines three 10-character segments 
of the buffer as A$, BS and ¢$. LSET at line 3% installs "12345" 
in the leftmost 5 of the first 1f characters of the buffer via the 
pointer A$. Similarly the second and third 19-character pieces of 
the buffer are set by lines 49 and 58. When run, this program gener- 


ates: 


RUNNH 
12345 67894 VWXYZ 
READY 


Note that no carriage return/line feed was output by the PUT state- 
ment. (The Monitor outputs a CR/LF sequence as the first part of 
the READY message.) 


LISTNH - 
OPEN "SSNOOPY+BAS" AS FILE 1 
ON ERROR GOTO 180 
OPEN "LPs FOR OUTPUT AS FILE 2» RECORDSIZE 512 
FIELD #15 512 AS AS 
FIELD #25 512 AS BS 
GET #1 
LSET BS = AS 

H PUT #2 

90 GOTO 6% 

104 CLOSE 122 

156 END 


READY 


Figure 11-2 
Record I/O Example #2 
Figure 11-2 is a program to move data froma file named "SNOOPY.BAS" 


in the system library (note the $ in the filename) onto the line prin- 
ter. Both the line printer and the disk file buffers are initialized to 512 
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characters. The FIELD statements at lines 4% and 5f set AS and BS 

to refer to these buffers. Data read at line 69 is transferred to 

the line printer buffer by the LSET statement (RSET would also be accept- 
able in this one case, since both A$ and BS are the same length) at line 
70. Then, at line 89, this data is output to the line printer. The 

loop terminates on end-of-file on attempting to read past the last 

block of the SNOOPY.BAS file via the ON ERROR GOTO mechanism. 


GET #2 
FOR X=9 TO 4280 STEP && 
FIELD #25 X AS AS» 88 AS BS 


Figure 11-3 
FIELD Statement Example 


FIELD statements can be used to perform blocking and deblock- 


ing of records where appropriate, as in Figure 11-3. 


19 DIM A$(99) 

20 OPEN "PP: FOR OUTPUT AS FILE 1s» RECORDSIZE 2aa 
30 FIELD #15 2*1 AS Z3s5 2 AS ASCI) FOR I=@ TO 99 
40 LSET ASCIZ) = CVTZSC1Z) FOR 1%=9% TO 99% 


546 PUT #1 
64 CLOSE 1 
999 END 


Figure 11-4 
CVT Function Example 


Figure 11-4 illustrates the use of the CVT functions to store 
numerical data in compact form as strings of binary bytes. The 
tape punched by this program has each integer represented on two 
frames of tape. A similar program could be written to read this 


binary tape. 
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11.7 THE XLATE FUNCTION 


The XLATE function is provided for use with Record I/0 to 
translate a string from one storage code into another. For 
example, while reading a magtape file, it might be necessary to 
translate from EBCDIC code to ASCII code so that data could be 
processed by the PDP-11. The XLATE function is of the form: 


XLATE (<string1>,<string2>) 


For example: 
X$ = XLATE(AS$,BS$) 


The first argument, <string1>, is the source string; the second 
argument <string2>, is the table string; the string value returned 
by XLATE is called the target string. Characters are taken 
sequentially from the source string, and the value of each charac- 
ter (@ to 255) is used as an index into the table string (that is, 

g means the first character of the table string, 1 means the second, 
etc.). The character value from the table string is appended to 
the target string unless the selected character in the table string 
has a value of @ or the table string is shorter than the index 
value. This means that the target string is equal to or shorter 


than the source string. 


For example, the following program removes all characters 
except "@%" to "9" and changes the characters "8" and "9" into 
wan and ab Sy ‘ 


LISTNH 

196 TS = "@1234567AB" 

114 TS = CHRS(G2)4TS FOR I%=0% TO 472 

129 REM - LINE 110 PUT @*S CORRESPONDING TU CODES @ TO 47 
130 INPUT S$ 'GET STRING TO TRANSLATE 
140 PRINT XLATECS$5TS$) 

150 END 

READY 

RUNNH 

2? LAXYZ34+-18987654321 

12349BA7654321 

READY 
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11.8 EXTENDING DISK FILES 


A disk file that is created by an OPEN FOR OUTPUT (or OPEN) 
statement has a length of @. As records are written, the file 
progressively grows in length; this growth is called extending the 
file. 


A more exact description of file extending is as follows: 


a) Is there room in the last cluster! of the file for 
the new record? 


b) If so, then the file length is increased and the 
previously unused space in that cluster is used. 


c) If not, then a new cluster is appended to the file. 
There is then room in the newest last cluster for 
the new record so condition b) applies. 


The amount of space actually allocated by the system to a file 
may be greater than the file length. For example, if the file 
clustersize is 4 and the first 6 records of that file have been 
written, the file is of length 6 but is actually allocated 8 records 
(2 clusters) of space. 


A file is extended by attempting to write beyond the current 
end-of-file. Hence, a program must have write privileges in order 
to be able to extend a file. There is an exception to the rule that 
having write access to a file permits a program to extend the file. 
In UPDATE mode (see Section 12.2) several programs can have simultane- 
ous write privileges on a single file. Nonetheless, if a program 
opens a file in this special UPDATE mode, that program may not extend 
the file. A file can only be extended when open in normal (non-UPDATE) 
mode. 


It is possible to extend a file by a number of records at one 
time. For example: 


196 OPEN "DATA" FOR OUTPUT AS FILE 1% 
206 PUT #125 RECORD 108% 


TNote that the file CLUSTERSIZE is the least increment by which a disk 
file can be extended. Normally the CLUSTERSIZE would be one record (see 
Section 9.2.2). 
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would create a file DATA and (when line 200 is executed) extend it 
immediately to 100 records. Since the system overhead for extending 
a file by a single record and by many records is nearly the same, it 
is much more efficient to immediately extend a newly created file to 
its final length than to extend it many times in increments of a 
single record. Whenever the final size of a file is known, the file 


should be extended to its full size in a single operation. 


A similar technique applies to virtual core arrays. For example: 


199 OPEN "DATA" FOR OUTPUT AS FILE 14 
299 DIM #ls AC199GQ) 
349 AC1GG9A)D = B 


This extends the virtual core array A to its final length. Virtual 
core arrays, however, are not initially zeroed by the system. In 
the example given above, A(f) through A(9999) contain indeterminate 
values. Unless the user is careful these values could cause a pro- 
gram failure. The user is advised to first zero the virtual core 
array. This could be done as follows: 


340 MAT 4 = ZERC1A900) 


However, this uses the more time consuming method of extending the 
file. A more optimal approach would be: 


3AM ACIAAAAZI=Az: MAT A = ZERC1IAGHO) 


which immediately extends the file to its maximum and then zeroes it 


sequentially. These techniques have frequent practical application. 
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CHAPTER 12 


DEVICE DEPENDENT I/O OPERATIONS 


This Chapter describes special programming techniques that are 
available in RSTS. These techniques permit the programmer full 
control over input and output operations on specific devices; for 
this reason they are called "device dependent" operations. The 
material covered in this Chapter assumes familiarity with Chapters 
9, 10, and ll. 


12.1 NOTES ON DISKS, PUBLIC AND PRIVATE 


In Chapter 9, the concept of device names for disks was intro- 
duced with little explanation of when a disk is to be referenced 
by name (e.g., DK2:) and when simply by default (i.e., no explicit 
device is specified). To clarify this, the concept of public disks 


and private disks must be explained. 


A private disk is one that belongs to only a few user accounts, 
conceivably to a single user account. Files can be created only 
under these accounts, and can be read (or written) by other users 
only if the protection code of the file permits. A user who does 


not have an account on a private disk cannot create a file on it. 


A public disk, on the other hand, is a disk on which any user 
can create files. Every user has an account on a public disk as 
soon as he references it. There is always at least one public disk 
on the system, which is called the "system disk". All public disks 
together on a system are called the "public structure" because the 
system itself treats all of the public disks together as a unit. For 
example, when a program creates a file in the public structure, that 
file is placed on the public disk with the most Space available. This 
is done to ensure proper distribution of files across the disks in 
the public structure. The actual determination of which disks on a 
particular system are public and which are private is left to the 
system manager. Therefore, this allocation will vary from system 
to system. 
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Private disks are always referenced by a specific name (namely, 
DK#: to DK7: or DPZ: to DP7:). The public structure is normally 
referenced by default; however, it has the specific name "DF:" 
(DK: and DP: are acceptable alternatives). While it is permissible 
to reference public disks by their specific names, this is not 
recommended; it might result in a file that exists elsewhere in the 
public structure not being found or even being deleted. The system 
will not allow two files of the same name for a single user to exist 
in the public structure. 


Private disks may be mounted and dismounted while the system 
is running. Private disks are normally loaded only when needed. 
Public disks should be kept permanently mounted. 


12.2 THE UPDATE OPTION FOR: DISK FILES’ 


In the description of disk files up to this point, the concept 
of simultaneous user access to a single file has been largely ig- 
nored. The system will permit several users to read from a single 
file simultaneously. However, a problem does arise if multiple users 
attempt to write onto a single file simultaneously. Two users could 
conceivably try to write the same record of the file, resulting ina 
loss of data. To avoid this conflict, the system permits only one 
user at a time to have write privileges on any given file. Thus, a 
user may fail to obtain write privileges even if the file is not 
protected against writing. If this occurs the user must close the 
file and reopen it at a later time, after the other user has finished 
with the file and closed it. 


It is exceptional for two users to have a file open simulta- 
neously. However, in certain applications (for example, sales 
order-entry applications) it might be normal for multiple users to be 
updating a single master file. In these cases it is not satisfactory 
to be constantly closing and reopening the file to obtain write 
privileges, as this is a time-consuming operation. For this reason 
a special UPDATE option is available with RSTS-11 that permits 
multiple users to have write access to a file while guarding against 


simultaneous writing of a single record. 


UPDATE is an optional feature of RSTS-11 and may not be available in 
all systems. UPDATE requires the Record I/O option. 
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To indicate that a file is being opened for UPDATE, the MODE 
specification is used when the file is opened. For example: 


100 OPEN "MASTER" AS FILE 145 MODE 1% 


when used with a disk file indicates that the file is opened for 
UPDATE!. In this case the program is granted write privileges 
unless such access is specifically prohibited by the protection code 
of the file. 


The system does not permit a file to be simultaneously open for 
UPDATE and in normal (non-UPDATE) mode. Attempting to open a file 
for UPDATE if it is already open by anyone in normal mode, or at- 
tempting to open a file in normal mode if it is already oven for 
UPDATE, results in a "PROTECTION VIOLATION" error. 


Once a file has been opened for UPDATE, any read operation on 
that file causes the record read to be put in a special "locked" 
state. This means that no other user is permitted to read or write 
that record until it is released (or unlocked) by the program that 
locked it. Attempting to read or write a record that another user 
has locked results in a "DISK BLOCK IS INTERLOCKED" error which can 
be caught with an ON ERROR GOTO statement. 


There are three ways for a program to unlock the record: 


1. The next write operation on the file unlocks 
the record. 


2. Executing an UNLOCK statement. This statement 
has the form: 


line number UNLOCK #<expr> 


where <expr> is the internal channel number 
of the file that is opened for UPDATE. 


3. Any error encountered while accessing the file unlocks 
the RECORD. 


To illustrate UPDATE, consider a simple inventory application 
where operators on several terminals can enter a part number and 
order quantities. Assume that the file is sequenced in such a 
fashion that the part number actually corresponds to the record 
number of the file that contains information about this part, and 


that the first four characters of the record contain the quantity 


‘The RECORDSIZE option may not be used on files that are opened for 
UPDATE. 
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available as a (2-word) floating-point number. For this example 
the remaining 598 characters are ignored. A program to handle 
updating the quantity available is as follows: 


LISTNH 

146 ON ERROR GOTO 14984 fFIND OUT AROUT EKROPS 
200 OPEN "INVENT.ORY’ AS FILE ls MODE 1 !OPEN FILE IN UPDATE MODE 
340% FIELD #ls 4 AS CS !c$ IS ATY IN FILE 

490 INPUT “PART NUMBER'SNS"QUANTITY"3Q {!GET PART # AND QTY 

59 GET #1, RECORD N 'READ APPROPRIATE RECOKD 
699% X=CVUTSFC(CS)-9 {COMPUTE OTY REMAINING 
700 IF X>=A THEN 81% !ENOQUGH ON HAND? 

710 UNLOCK #1 !PERMIT OTHER ACCESSES 


729 PRINT “ONLY CUTSFC(CS) "ITEMS IN STOCK" 
!SEE IF ORDER WILL BE 


730 GOTO 4Aa9 ! CHANGED 

849 LSET CS=CVTFECX) !STORE NEW OTY ON HAND 

854 PUT #15 RECORD N REWRITE INTO FILE 

909 GOTO 44% !NEXT TRANSACTION 

1999 IF ERR <>19 THEN ON ERROR GOTO 4 ! IGNORE NON-INTERLOCK ERRORS 
1148 PRINT "WAITING" !'LET HIM KNOW WE'RE HERE 
1°40 SLEEP 5 !tVAIT FOR CURRENT ACCESS 
1300 RESUME ITRY AGAIN 

149% END 

READY 


12.3 MAGTAPE INPUT/OUTPUT OPERATIONS 


Magtape I/O is processed under RSTS-11 as one of two forms: 
file-structured magtape and non-file structured magtape. File- 
structured magtapes are always written with 512-byte blocks at 899 
BPI (dump mode on 7-track tape) and odd parity. Each file is pre- 
ceded by a magtape file label record; these files are completely 
DOS-11 compatible. 


Non-file structured magtapes may contain records of any size (up 
to about 4K bytes) with any acceptable density or parity settings. 


Conventionally, the last record on any magtape is followed by 
three EOF (End-of-File) records to signify end of data on that tape. 
In order to use the tape for file-structured processing, it must 
first have these three EOF records written onto it. This can be done 
by zeroing the magtape with PIP (see the RSTS-1l1 System User's Guide). 
For example: 

SUNS PIP 


PIP - RSTS V4A-11 SYSTEM #213 
aMTOS /Z1 


would write three EOF records at the beginning of the magtape on 
unit §@. 
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Magtape output can only be done following the end of all previ- 
ous data on that magtape. New files begin immediately subsequent to 
the last file on the tape. New output is placed on the tape following 
the first end-of-file record written at the end of the last output 
operation; the other two EOF records are erased when the new file is 
created. The new file, then, has three FOF records written to ter- 
minate that file. 


12.3.1 The File-Structured Magtape OPEN 


File-structured processing on magtape permits device independent 
programming and tape interchange with DOS-11 programs. To distinguish 
between file-structured and non-file structured processing, a file 
name must be specified in the OPEN statement. For example: 


198 OPEN "MT#:ABC" FOR INPUT AS FILE 1% 


In this example, the file "ABC" is to be read from magtape unit @. 

The magtape is rewound and the file "ABC" is located. The file is 
write protected by the system (on magtape, therefore, OPEN FOR INPUT 
means literally for input only). If the file "ABC" is not located, 

a "CAN'T FIND FILE OR ACCOUNT" error occurs. There are two other 
forms of the file-structured Magtape OPEN statement: OPEN FOR OUTPUT, 
and the simple OPEN. For example: 


198 OPEN "MT#:ABC" FOR OUTPUT AS FILE 1% 


This statement causes the magtape on unit ff to be rewound and a 
search for the file "ABC" to be performed. If the file is located, 
an error occurs. If the file is not located, a file label is writ- 
ten following the last file on the tape, and the tape is left open 
for writing. In this case, the file is read protected, so only 
output may be done. An example of the third form of the OPEN state- 
ment is as follows: 


1g@ OPEN "MT@:ABC" AS FILE 1% 


Here neither FOR INPUT nor FOR OUTPUT is specified. This statement 

causes the tape to be rewound, and a search for the file "ABC" to be 
made. If the file is found, an OPEN FOR INPUT is performed; if the 

file is not located, an OPEN FOR OUTPUT occurs. This is not a 
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recommended method for processing magtape since the program cannot 
immediately determine which type of OPEN was performed. 


12.3.2 File-Structured Magtape File Labels 


To uniquely identify each file on the magtape, the file itself 
‘s preceded by a file label. The file label is a 14-byte (7-word) 


record that contains the following information: 


Table 12-1 


Magtape File Label Structure 


Filename (Radix-5f), characters 1-3 
Filename (Radix-5@), characters 4-6 
File extension (Radix-59) 
Project-Programmer number 
Protection code (always 155) 

g (not used by RSTS-11) 
Creation date 

@ (not used by RSTS-11) 


The project-programmer number is the account number of the current 
user, unless some other number is specified in the OPEN statement. 
If magtapes are to be interchanged with DOS-11l systems, a problem 
May occur as RSTS-11l treats project-programmer numbers as decimal 
values, and DOS-1l treats this number (called a UIC under DOS-11) as 
an octal value. To avoid interchange problems it is suggested that 
all files on the tape be written with a [1,1] project-programmer 
number, which is the same in both decimal and octal. For example: 


199 OPEN "MT@:ABC[1,1]" FOR OUTPUT AS FILE 1% 


would accomplish this. Note that the project-programmer number is 
part of the filename string. There could be several files named 

"ABC" on a tape having different project-programmer numbers associated 
with them. Often a failure to find a file on a magtape is the result 


of forgetting to specify the correct account number. 


The protection code written in the file label is always 155 deci- 
mal (233 octal) which is acceptable to DOS-11 (RSTS-11 and DOS-11 


use different protection code values). RSTS-11 ignores the value of 
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the protection code when reading the file. This avoids interchange 
conflicts with DOS-1l. 


12.3.3 The File-Structured Magtape CLOSE Statement 


The CLOSE statement is used when the processing of a magtape 
file is completed. If the file was open for output, three EOF 
records are written when the file is closed to mark the end of data 
on the tape. In all cases, if file-structured magtape processing was 


used, the tape is rewound when the file is closed. 


12.3.4 The Non-file Structured Magtape OPEN Statement 


In non-file structured processing there are no special file 
label records written on the tape. Essentially, the system passes 


the data directly from the magtape to the user program. Therefore, 
tapes of almost any format can be read or written with non-file 


structured magtape operations, as long as the program is itself 
set up to handle the actual tape format correctly. 

In the OPEN statement, only a magtape unit is specified to 
indicate non-file structured processing, no filename would be 
specified. There are three forms for the OPEN statement, as 
before. These are: 

1g OPEN "MT@:" FOR INPUT AS FILE 1% 
or 


198 OPEN "MT@:" AS FILE 1% 


OPEN FOR INPUT and the simple OPEN statements are equivalent. No 
magtape movement occurs and both reading and writing of records 


is permitted. The third form is slightly different: 


198 OPEN "MT@:" FOR OUTPUT AS FILE 13 


In this example, the OPEN FOR OUTPUT permits only writing. This is 
the normal way of opening a magtape for writing. 
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12.3.5 The Non-file Structured Magtape CLOSE Statement 


CLOSE has no special action on non-file structured magtapes 
unless OPEN FOR OUTPUT was used. On a magtape that was OPEN FOR 
OUTPUT, the CLOSE statement causes three EOF records to be written, 
followed by backspacing over two of these EOF's, to position the tape 


correctly for subsequent output operations. 


In any case, if the magtape was open for non-file structured 


processing, then it is not rewound on CLOSE. 


12.3.6 The MODE Specification 


With non-file structured magtape processing on 7-track magtape, 
a MODE specification can be used in the OPEN statement to define the 


tape density and parity. This parameter is formatted as follows: 


Line number OPEN<string>AS FILE <expr>, MODE D*4+P 


where: 
D = density 
@ = 268 BPI 
1 = 556 BPI 
2 = 899 BPI 
3 = 89 BPI, dump mode? 
P = parity 
@ = odd parity 
1 = even parity 


Where MODE is not specified, the tape is processed in odd parity 

at 89M BPI (and dump mode for 7-track tapes). The MODE specification 
is ignored on 9-track magtapes which are always processed in odd 
parity at 899 BPI. 


lon 9-track tapes, one line of the tape equals one byte of data. On 
7-track tape each line contains only 6-bits. This means that on 
writing the tape the high two bits of each byte are lost and on read- 
ing the tape the high two bits of each byte are set to zero. In dump 
mode, each byte is written as two lines of tape, four bits per line, 
and on reading, the low four bits of two consecutive lines are com- 
bined to form a byte of data. In dump mode the high two bits of each 
line on the magtape are zero. 
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For example: 


198 OPEN "MT@:" AS FILE 1%, MODE 5% 


would open magtape unit @ (assuming a 7-track drive) with 556 BPI 


and even parity. 


12.3.7 The MAGTAPE Function 


The MAGTAPE function provides flexibility in non-file structured 
processing by permitting the program control over all magtape func- 
tions. The general form of the MAGTAPE function is as follows: 


I% = MAGTAPE (F%,P%,U%) 


where: 
FS is the function code (1 to 7) 
PS is the integer parameter 


Us is the internal channel number on which 
the selected magtape is open 


I% is the value returned by the function 


The actual effect of executing the MAGTAPE function is determined 
by the function code, F%. These functions are described in the 
Sections which follow. In all examples in these Sections, assume 
that magtape unit 1 had been opened on internal channel 2. That is, 
the following statement had been executed prior to executing the 


MAGTAPE function: 
198 OPEN "MT1:" AS FILE 23 


12.3.7.1 Off-Line (Rewind and Unload) Function 


Function code = 1 
Parameter = unused 
Value returned = g 


The Off-Line function causes the specified magtape to be 


rewound and set to NOT READY. For example: 
2608 I% = MAGTAPE(1%,9%,2%) 


rewinds and unloads the magtape open on internal channel 2. 
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12.3.7.2 WRITE End-of-File Function 


Function code = 2 
Parameter = unused 
Value returned = g 


The WRITE End-of-File function writes one EOF record at the 
current position of the magtape. For example: 


208 I% = MAGTAPE (2%,8%,23) 


writes a EOF on the magtape that is open on internal channel 2. 


12.3.7.3 Rewind Function 


Function code = 3 
Parameter = unused 
Value returned = ¢g 


The Rewind function causes the selected magtape to be rewound. 


For example: 


298 I% = MAGTAPE (3%,9%,2%) 


rewinds the magtape open on internal channel 2 (this function does 


not cause the magtape to be set to NOT READY, unlike function code 1). 


12.3.7.4 Skip Record Function 


4 

number of records to skip (1 to 32767) 
number of records not skipped (@ unless 
EOF encountered) 


Function code 
Parameter 
Value returned 


The Skip Record function causes the magtape to advance down the 
tape. The tape continues to advance until either the desired number 
of records are skipped (in which case the value returned by the 
function is §) or an EOF record is encountered (in which case the 
value returned is the specified number of records to skip minus the 
number actually skipped). For example, to skip from the current tape 
position to just past the next EOF, the following function could be 


used: 


209 I% = MAGTAPE(4%,32767%,2%) 
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This assumes that it is known that there are fewer than 32767 records 
before the next EOF. In section 12.3.7.7, a more complex example 
using the MAGTAPE function shows how to skip an entire file regard- 


less of the number of records. 


12.3.7.5 Backspace Function 


5 

number of records to backspace (1 to 32767) 
number of records not backspaced (ff unless 
EOF or beginning-of-tape encountered) 


Function code 
Parameter 
Value returned 


The Backspace function is similar to the Skip function, except that 
the tape motion is in the reverse direction. The beginning-of-tape 
(BOT or Load Point) as well as EOF records can cause premature 
termination of the Backspace operation (in which case the value 
returned is the specified number of records to backspace minus the 
number actually backspaced). The BOT is neither skipped nor counted 


as a skipped record. For example: 
288 1% = MAGTAPE(5%,1%,23) 


would backspace one record on the magtape opened on internal channel 


2, unless the tape was already at BOT. 


12.3.7.6 Set Density and Parity Function 


6 
D*4+P 
g@ (see note) 


Function code 
Parameter 
Value returned 


where: 
D = Density 
g = 209 BPI 
1 = 556 BPI 
2 = 898 BPI 
3 = 898 BPI, dump mode 
P = Parity 
g@ = odd 
1 = even 


This function changes the density and parity of 7-track magtapes 
to any selected:value. It is interpreted in exactly the same fashion 
as the MODE specification in the OPEN statement (see Section 12.3.6). 
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On 9-track magtape a density of 8ff BPI with odd parity is always 
used, and the density and parity function is ignored if used. For 


example: 


298 1% = MAGTAPE(6%3,9%,2%) 


would change the density and parity of the 7-track magtape opened on 


internal channel 2 from its current setting to 8#@ BPI, even parity. 


Cre 


File-structured magtapes must be written at 899 
BPI dump mode with odd parity. Attempting to 
use the MAGTAPE function to change the density 
and parity of a file-structured magtape is an 
error. In this case the function has no effect, 
and the value returned is equal to the parameter 
passed (D*4+P) rather than @. 


12.3.7.7 Tape Status Function 


Function code = 7 
Parameter = unused 
Value returned = status 


The function returns the status of the specified magtape as 


a 16-bit integer, with certain bits set depending on the current 
status. The format is shown in Table 12-2. For example, to obtain 


the status of the magtape opened on internal channel number 2: 
268 I% = MAGTAPE (7% ,8%,23%) 


If the value of I% returned were 25,681 (decimal, or 62981 octal) 
this would mean that it was 8#@ BPI, 9-track, odd parity, write 
protected, and that the last command issued was to the file 

and was READ. As another example of the use of the magtape status 
function, suppose that a program wanted to advance to the next EOF 
(i.e., skip over the current file). The Skip Record function could 
do this, unless the file were longer than 32,767 records -- in which 
case several skip record functions must be executed. The following 
program statement executes a Skip Record function until the 


next EOF is encountered: 


208 I% = MAGTAPE (4%, 32767%,2%) : 
IF (MAGTAPE(7%,%%,2%) AND 128%)=0% THEN 289 
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Table 12-2 


Magtape Status Word 


Meaning 
IS<Py Last command caused an error 


298 BPI 
556 BPI 
889 BPI 
880 BPI, dump mode 


(Ig AND 24576%)/8192% Density: @ 
1 


2 
3 


496%) 9-track tape 
496%) 7-track tape 


28483) Odd parity 
28483) Even parity 


1924%) Magtape is physically write locked 
512%) Tape is beyond end-of-tape marker 


256%) Tape is at beginning-of-tape (Load 
Point) 


128%) Last command detected an EOF 


643) The last command was READ and the 
record read was longer than the I/O 
buffer size (i.e., part of the rec- 
ord was lost). 


Unused 


I% AND 7% Indicates last command issued: 


g OFF-LINE 

1 READ 

WRITE 

WRITE EOF 

REWIND 

SKIP RECORD 
BACKSPACE RECORD 


iu di wu a 
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12.3.8 Magtape Error Handling 


For processing magtapes in a sophisticated fashion, it is impor- 
tant to consider details of the system's handling of special magtape 
error conditions. These are: parity error, record length error, 


off-line (not ready) error and write lock error. 


PARITY ERROR (also Bad Tape Error) 


On input operations, the system attempts to read the record 15 
times. If the error condition persists, a "USER DATA ERROR ON 
DEVICE" error occurs. In this case, the read has been completed, but 
the data in the I/O buffer cannot be considered correct. On an output 
operation, if the first attempt to write a record fails, the system 
attempts to rewrite the record 15 times using write with Extended 
Interrecord Gap to space past a possible bad spot on the tape. If 
the error condition persists, a "USER DATA ERROR ON DEVICE" error 
occurs. In both cases, the tape is positioned just past the record 


on which the error occurred. 
RECORD LENGTH ERROR 


This error can only occur during a read operation when the record 
on the magtape is longer than the I/O buffer size, as determined by 
the OPEN statement. The extra bytes in the record are not read into 
memory but are checked for possible parity errors. No I/O error is 
returned to the user progran; however, Bit 6 of the magtape status 
word is set. Therefore, if a program is reading records of unknown 
length from magtape, it is necessary to check for possible record 
length errors after every read operation. This can be done as follows: 


288 PRINT “RECORD TOO LONG" IF MAGTAPE(7%,8%,2%) AND 642% 


Note that in the above example a non-zero integer tests as TRUE. 


OFF-LINE ERROR 


If the magtape unit is not ready, a "DEVICE HUNG OR WRITE LOCKED" 


error occurs. 
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WRITE LOCK ERROR 


Attempting any write operation on a magtape that is physically 
write locked (i.e., a tape that does not have the write enable ring 
inserted) results in a "DEVICE HUNG OR WRITE LOCKED" error. 


12.3.9 The KILL and NAME AS Statements 


The KILL and NAME AS statements described in Sections 9.8 and 
9.7 are applicable only to disk and DECtape files, and cannot be used 
with magtape files. 


12.4 CARD READER USAGE 


The card reader reads cards punched with the standard codes, as 
shown in Appendix D. One of the three sets of codes may be used on 
a particular RSTS-11 system: §29, 926, and 1491 EBCDIC. Cards 
punched in other formats are not acceptable to RSTS-ll. The end-of- 
file card for RSTS-11 contains a 12-11-@-1 punch in card column 1?. 
Reading an end-of-file card causes an "END OF FILE ON DEVICE" error 
to occur, which can be trapped with an ON ERROR GOTO statement. 


RSTS-11 always suppresses trailing blanks on a card and always 
adds a carriage return and a line feed character to the end of the 
data read from the card. For example, consider a card punched as 


follows: 


ABCDEFGHIJKLMNOPQRSTUVWXYZ 


(columns 1 to 26 are punched, 27 through 80 are blank), and the fol- 


lowing program executes as shown: 


1gg OPEN "CR:" AS FILE 1% 
11g INPUT LINE #1%, AS 
128 PRINT LEN (AS) 

139 PRINT ty" AS new 

148 END 


RUNNH 
28 
>ABCDEFGHIJKLMNOPQRSTUVWXYZ 


< 


‘A card containing a 12-11-0-1-6-7-8-9 punch in column 1 is also ac- 
cepted as an end-of-file card. 
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In this example the trailing spaces in card columns 27 through 80 are 
deleted, and the characters carriage return/line feed are added 
(making a total of 28 characters in the string A$). Cards can be 
read with INPUT, INPUT LINE or GET statements. 


If a card is misread, or contains any illegal punches, a 
"USER DATA ERROR ON DEVICE" error occurs. If the card was read 
with a Record I/O GET statement, then any characters that contain 
illegal punches are read as RUBOUT's (ASCII 127 codes). Therefore, 


the program can determine in which column(s) the error(s) occurred. 


12.5 LINE PRINTER OPTIONS 


12.5.1 Special Character Handling 


Certain characters have special characteristics on line printer 


output. These are summarized in Table 12-3. 


Table 12-3 
Special Line Printer Characters 


Character Function 


CHRS (9) TAB, spaces over to next tab position 
(columns 1, 9, 17, 25, etc.) 


CHRS (19) Line feed 


CHRS (12) Form feed (ignored if forms length # 66, 
see Section 12.5.2) 


CHRS (13) Carriage return (may be used for over- 
printing on the LP11) 


CHR$ (96) to CHRS$(126) Lower case printing characters, converted 
to upper case except on an upper/lower 
case printer. 


12.5.2 The LPFORM Option’ 


The LPFORM option permits a program to handle non-standard 
length forms in the line printer*. To accomplish this, the forms 


1LPFORM is an optional feature of RSTS-11 and may not be available on 
all systems. LPFORM requires the Record I/O option. 


*The hardware option on the LP1l to automatically skip over perfora- 
tions must be disabled for this option to execute properly. 


12-16 


length may be specified in the OPEN statement using the MODE speci- 


fication (otherwise a forms length of 66 lines per page is assumed). 


When certain special characters are sent to the printer, they 
are interpreted as signifying the line number of the next line on 
which to print (RSTS-11 skips down to this line by sending the proper 
number of line feed characters to the printer). 


The OPEN statement would have the following form: 
line number OPEN "LP:" AS FILE <expr>, MODE <expr> 


In this case the MODE expression is the form size, which may be from 
1 to 126 lines per page. For example: 


1g OPEN "LP:" AS FILE 1%, MODE 243% 


sets the form length to 24 lines per page. Lines are numbered 
from @ to length-1; so in this example the lines are numbered g 
through 23. 


Characters whose values lie between g and 127 are output as their 
ASCII equivalents. A character whose value is greater than or equal 
to 128 is treated as follows: 128 is subtracted from the value. If 
the resulting value is greater than the (page length - 1), it is ig- 
nored. If the resulting value is less than the page length but 
greater than the current line number, the printer skips to thet line 
on the current page. If the resulting value is less than or equal to 
the number of the current line, the printer skips to the appropriate 
line on the next page. 


For example, to print a page header on line 2 and a page trailer 
on line 2, the following statements could be executed: 


298 PRINT CHRS$(128%+2%); “PAGE HEADER" 
218 PRINT CHR$(128%+29%); “PAGE TRAILER" 


The system operator must ensure that the paper is initially set at 


line @ for the form control to function properly. When the form 
length is set to some value other than 66 lines per page, form feed 
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characters (CHR$(12)) are ignored. In this case a form eject is not 
done by the system when the printer is closed. 


The LPFORM option has one additional capability. In some appli- 
cations it is preferable to print the character "0" in place of the 
character "§". For example, a bill for one thousand dollars should 
be printed as $1,000.00 rather than $1,888.88. To accomplish this, 
simply add 128 to the MODE with which the line printer is opened. 

For example, to open the line printer with a form length of 24 and 


convert all @'s to O's, the following statement would be proper: 
198 OPEN "LP:" AS FILE 1%, MODE 152% 


(since 152=128+24). 


12.6 USING VT@5 (AND VT#6) DISPLAY TERMINALS 


The VT@5 and VT@6 alphanumeric display terminals recognize 
certain control characters that are not used on Teletypes. These are 
summarized in Table 12-4. 
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Table 12-4 


Special Display Terminal Characters 


Character Meaning 


CHRS (8) BACKSPACE (move cursor left one character) 
CHRS (11) CURSOR DOWN (one line, same position) 


CHRS (14) Direct cursor control (VT#5 only). 
The next two characters give x- and 
y- coordinates of the new cursor position 
on the 20-line by 72-character VT@{5 screen. 


The characters following CHRS$(14) are, 
first, CHR$(32+Y) and second, CHRS$(32Z+X). 
Y is the y-coordinate, (@ to 19), and xX 
is the x-coordinate (@ to 71). 


CHR$ (24) CURSOR RIGHT 
CHRS$ (25) CURSOR LEFT? 


CHR$ (26) CURSOR UP (one line, same position) 


CHRS (28) HOME DOWN’ (move cursor to lower left 
hand corner of display screen) 


CHRS (29) HOME UP (move cursor to upper left hand 
corner of display screen) 


CHRS (39) ERASE EOL (erase to end of line) 


CHRS (31) ERASE EOS (erase to end of screen) 


luse of these characters is not recommended on a VT#@5 terminal. 
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APPENDICES 


The following pages contain a summary 
of the BASIC-PLUS language, the commands 


described in the RSTS-1l System User's 
Guide, error messagés and other such 


material. 


APPENDIX A 
BASIC-PLUS LANGUAGE SUMMARY 


A.1 SUMMARY OF VARIABLE TYPES 


Type 
Floating Point 
Integer 
Character String 


Floating Point 
Matrix 


Integer Matrix 


Character String 
Matrix 


Variable Name 


single letter 
optionally followed by a 
single digit 


any floating point variable 
name followed by a % character 


any floating point variable 
name followed by a $ character 


any floating point variable 
name followed by one or two 
dimension elements in 
parentheses 


any integer variable name 
followed by one or two dimen- 
sion elements in parentheses 


any character string variable 
name followed by one or two 
dimension elements in paren- 
theses 


A.2 SUMMARY OF OPERATORS 


Type 
Arithmetic 


Relational 


Logical 


String 


Matrix 


Operator 


- unary minus 

+ exponentiation 

*,/ multiplication, division 
+,- addition, subtraction 
equals 

less than 

less than or equal to 


greater than or equal to 
not equal to 
approximately equal to 


< 
< 
> greater than 
> 
< 


vou 


NOT logical negation 
AND logical product 

OR logical sum 

XOR logical exclusive or 
IMP logical implication 
EQV logical equivalence 


+ concatenation 


+,- addition and subtraction 


of matrices of equal dimen- 


sions, one operator per 


statement 

* multiplication of con- 
formable matrices 

* scalar multiplication of 


a matrix, see Section 7.5.1 


Examples 


A 
I 
X3 


BS 
D7% 


MS 
R1$ 


S(4)  E(5,1) 
N2(8) V8(3,3) 


A%$(2) 1%(3,5) 
E3%(4) R2%(2,1) 


C$(1) S$ (8,5) 
A2$ (8) V1$ (4,2) 


Operates Upon 


numeric variables 
and constants 


string or 
numeric variables 
and constants 


== undefined 
for strings 


relational ex- 
pressions composed 
of string or 
numeric elements 
with relational 
operators 


string constants 
and variables 


dimensioned vari- 
ables. See Sec- 
tion 7.6.1 for 
further details. 


A.3 SUMMARY OF FUNCTIONS 


Under the Function column, the function is shown as: 
Y=function 


where the characters % and $ are appended to Y if the value returned 
is an integer or character string. 


A floating value (X), where specified, can always be replaced 
by an integer value. An integer value (N%) can always be replaced 
by a floating value (an implied FIX is done) except in the CVT$%$ 
and MAGTAPE functions (the symbol I% is used to indicate the neces- 
sity for an integer value). 


Type Function Explanation 
Mathematical =ABS (X) returns the absolute value of X, 
Y=ATN (X) returns the arctangent of X in radians. 
Y=COS (X) returns the cosine of X in radians, 
Y=EXP (X) returns the value of etX, where e=2.71828, 
Y=FIX (X) returns the truncated value of X, 
SGN (X) * INT (ABS (X) ) 
Y=INT (X) returns the greatest integer in X which 
is less than or equal to X., 
Y=LOG (X) returns the natural logarithm of X, log,X. 
Y=LOG19 (XK) returns the common logarithm. of xX, log, 9X. 
Y=PI has a constant value of 3.14159 
Y=RND returns a random number between #@ and l, 
Y=RND (X) returns a random number between @ and 1, 
Y=SGN (X) returns the sign function of X, a value 
of 1 preceded by the sign of X, 
Y=SIN(X) returns the sine of X in radians. 
Y=SQR (X) returns the square root of X 
Y=TAN (X) returns the tangent of X in radians, 
Print Y¥%=POS (X%) returns the current position of the print 


head for I/9 channel X, 9 is the user's 
Teletype. (This value is imaginary for 
disk files.) 

YS=TAB (X%) moves print head to position X in the cur- 
rent print record, or is disregarded if 
the current position is beyond X. (The 
first position is counted as 8.) 


String Y¥%=ASCII (AS) returns the ASCII value of the first char- 
acter in the string AS. 
YS$=CHRS (X%) returns a character string having the 


ASCII value of X. Only one character 
is generated. 

YS=CVTSS$ (13) maps integer into 2-character string, see 
Section 11.5. 

YS=CVTFS (X) maps floating-point number into 4- or 8- 
character string, see Section 11.5. 

Y%=CVTS% (AS) maps first 2 characters of string A$ into 
an integer, see Section 11.5. 


Y=CVTSF (AS) maps first 4 or 8 characters of string A$ 
into a floating-point number. See Sec- 
tion 11.5. 
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Type Function Explanation 


String, YS=LEFT (AS ,N%) returns a substring of the string A$ 
cont'd. from the first character to the Nth 
character (the leftmost N characters). 
YS=RIGHT (A$ ,N3%) returns a substring of the string A$ 


from the Nth to the last character; 
the rightmost characters of the string 
starting with the Nth character. 
YS=MID(A$,N1%,N2%) returns a substring of the string A$ 
starting with the Nl and being N2 
characters long (the characters 
between and including the Nl 
to N1+N2-1 characters). 
Y%=LEN (AS) returns the number of characters in the 
string A$, including trailing blanks. 
¥%=INSTR(N1%,A$,B$) indicates a search for the substring 
BS within the string A$ beginning at 
character position Nl. Returns a 
value @ if BS is not in AS, and the 
character position of BS if BS is 
found to be in AS (character posi- 
tion is measured from the start of 
the string). 


YS=SPACES (N$) indicates a string of N spaces, used 
to insert spaces within a character 
string. 

YS=NUMS (N%) indicates a string of numeric charac- 


ters representing the value of N as 
it would be output by a PRINT state 


ment. For example: NUMS(1.999@) 
(space) 1l(space) and NUMS(-1.999f) 
-l(space). 

Y=VAL (AS) computes the numeric value of the 
string of numeric characters AS. 
If AS contains any character not 
acceptable as numeric input with 
the INPUT statement, an error re- 
sults. For example: 


VAL ("15")=15 


YS$=XLATE (A$,BS) translate AS to the new string Y$ 
by means of the table string BS, 
see Section 11.7. 


System YS=DATES (93) returns the current date in the fol- 
lowing format: 
@2-Mar-71 
YS$=DATES (N$%) returns a character string correspond- 


to a calendar date as follows: 
N=(day of year)+[(number of 
years since 1970) *1000] 


DATES (1) = "1-Jan-79" 
DATES (248) = "@5-May-79" 
Y$=TIMES (#3) returns the current time of day as a 
character string as follows: 
TIMES (9) = "95:39 PM" 
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Matrix 


Magtape 


Function 


YS=TIMES (N%) 


Y=TIME (9%) 
Y=TIME (18) 


Y=TIME (2%) 


Y%=ERR 


Y%=ERL 


Y¥%=SWAPS (N%) 


YS=RADS (N%) 


MAT Y=TRN (X) 
MAT Y=INV(X) 


Y=DET 


Y¥3=NUM 


Y¥%=NUM2 


Explanation 


returns a string corresponding to the 
time at N minutes before midnight, 
for example: 


TIME$(1) = "11:59 PM" 
TIMES (1449) = "12:99 Am" 
TIMES (721) = "11:59 AM" 


returns the clock time in seconds since 
midnight, as a floating point number. 

returns the central processor time used 
by the current job in tenths of seconds. 

returns the connect time (during which 
the user is logged into the system) 
for the current job in minutes. 

returns value associated with the last 
encountered error if an ON ERROR GOTO 
statement appears in the program. 
See Section 8.4. 

returns the line number at which the 
last error occurred if an ON ERROR 
GOTO statement appears in the pro- 
gram. See Section 8.4.3. 

causes a byte swap operation on the 
two bytes in the integer variable N%. 

converts an integer value to a 3- 
character string and is used to con- 
vert from Radix-5@ format back to 
ASCII. See Appendix D. 


returns the transpose of the matrix X, 
see Section 7.6.2. 

returns the inverse of the matrix X, 
see Section 7.6.2. 

following an INV(X) function evaluation, 
the variable DET is equivalent to the 
determinant of X. 

following input of a matrix, NUM con- 
tains the number of elements entered 
in the last row. 

following input of a matrix, NUM2 con- 
tains the number of rows input. 


Y3=MAGTAPE (11%,12%,13%) 


Y¥%=RECOUNT 


provides program control over magtape 


operations by means of several func- 
tion specifications. See Section 
12.3.7. 


returns the number of characters read 


following every input operation. 
Used primarily with non-file struc- 
tured devices. See Section 11.3.1. 


A.4 SUMMARY OF BASIC-PLUS STATEMENTS 


The following summary of statements available in the BASIC-PLUS 
language defines the general format for the statement as a line in a 
BASIC program. If more detailed information is needed, the reader is 
referred to the section(s) in the manual dealing with that particular 
statement. 


In these definitions, elements in angle brackets are necessary 
elements of the statement. Elements in square brackets are necessary 
elements of which the statement may contain one. Elements in braces 
are optional elements of the statement. 


Where the term line number ({Zine number}) is shown in braces, 
this statement can be used in immediate mode. 


The various elements and their abbreviations are described below: 
vartable or var Any legal BASIC variable as described in A.1l 


or Section 2.5.2. 


line number Any legal BASIC line number described in 
Section 2.2. 


expression OY exp Any legal BASIC expression as described in 
Section 2.5. 


message Any combination of characters. 

condition or cond Any logical condition as described in Sec- 
tion 3.5. 

constant Any acceptable integer constant (need not 


contain a % character). 
argument(s) Or arg Dummy variable names. 
statement Any legal BASIC-PLUS statement. 


string Any legal string constant or variable as 
described in Section 5.1. 


protectton Any legal protection code as described in 
Section 9.1. 


value(s) Any floating point, integer, or character 
string constant. 


-list The legal list for that particular statement. 

dimenston(s) One or two dimensions of a matrix, the maxi- 
mum dimension(s) for that particular state- 
ment. 


Statement Formats and Examples Section 
REM 
{line number} REM <message> 3.1 
{line number}{<statement>}!<message> 
1g REM THIS IS A COMMENT 
15 PRINT ! PERFORM A CR/LF 
LET 
{Line number} {LET} <var>{,<var>,<var>...} = <exp> 3.2 
55 LET A=4f%: B=22 
68 B,C,A=4.2 !MULTIPLE ASSIGNMENT 
DIM 
line number DIM<var(dimenston(s))> 3.6.2 
1g DIM A(2@), B$(5,1%), C%(45) 7.1 
Line number DIM #<constant>,<var(dimenston(s))>=<ceonstant>9.6.1 
75 DIM #4, A$(10f)=32,B(59,59%) 9.6.2 
RANDOMIZE 3.7.2 
Zine number RANDOM{1IZE} 
55 RANDOMIZE 
78 RANDOM 
IF-THEN, IF-GOTO THEN<statement> 
line number IF <cond> [ suet nunben>] 3.5 
GOTO<line number> 
55 IF A>B OR B>C THEN PRINT "NO" 
6@ IF FNA(R)= B THEN 250 
95 IF L<xt2 AND L<>@ GOTO 345 
IF-THEN-ELSE 8.5 


line number 


FOR 
line number 


29 
55 


FOR-WHILE, FOR-UNTIL 


line number 


NEXT 
line number 
25 


69 


Manual 


THEN<statement> 
<cond> | THEN<line number> ELSE<statement> 
GOTO<line number> 


A>N THEN 289 ELSE PRINT A 
B==R THEN STOP ELSE 89 


FOR 


FOR 
FOR 


<var>= <exp>TO <exp> {STEP<exp>} 3. 


I=2 TO 49 STEP 2 
N=A TO A+R 


FOR 


FOR I 
FOR N 
FOR 


<var> = <exp> {STEP<exp>} 


1 STEP 3 WHILE I<x 
2 STEP 4 UNTIL N>A OR N=B 
B= 1 UNTIL B>1¢ 


WHILE 
va <cond> 


NEXT <var> 
NEXT I 
NEXT N 


ELSE<line number> } 
B=A THEN PRINT “EQUAL" ELSE PRINT "NOT EQUAL" 


, 


6.1 


8.6 


Manual 


Statement Formats and Examples Section 
DEF, single line 3.7.3 
line number DEF FN<var>(arg) =<exp(arg)> 5.5.1 
28 DEF FNA(X,Y,2)=SQR(X+2+¥+2+Z42) 6.4 
DEF, multiple line 
line number DEF FN<var>(arg) 8.1 
<statements> 
line number FN<var>=<exp> 
line number FNEND 
1g DEF FNF(M) !'FACTORIAL FUNCTION 
2@ IF M=1 THEN FNF=1 ELSE FNF=M*FNF (M-1) 
39 FNEND 
GOTO 3.4 
line number GOTO <line number> 
1gg@ GoTO 59 
ON-GOTO 
line number ON <exp> GOTO <list of line numbers> 8.2 
75 ON X GOTO 95, 158, 45, 299 
GOSUB 
line number GOSUB <line number> 3.8.1 
98 GOSUB 299 
ON-GOSUB 
line number ON <exp> GOSUB <list of line numbers> 8.3 
85 ON FNA(M) GOSUB 299, 259, 49%, 375 
RETURN 
line number RETURN 3.8.2 
375 RETURN 
CHANGE 552 
—, - Pe 
{line number} CHANGE Se ua TO Bone one 
string var>. <array name>-- 
25 CHANGE A$ TO X 
78 CHANGE M TO R$ 
75 CHANGE B TO B$ 
OPEN 9.2 
P : NPUT 9.2.1 
{line number} OPEN<s tring>{FOR( OMe Orr JAS FILE <exp> goo 
{,RECORDSIZE<exp>}{,CLUSTERSIZE <exp>}{,MODE <exp>} 
1g OPEN "PP:" FOR OUTPUT AS FILE Bl 9.6.3 
28 OPEN "FOO" AS FILE 3 
38 OPEN "DT4:DATA.TR" FOR INPUT AS FILE 19 
CLOSE 9.5 
{line number} CLOSE <list of exp> 11.2 
1@@ CLOSE 2 
255 CLOSE 1f, 4, Nl 
3.3.1 
READ 5.3 
line number READ <list of vartables> 6.3 
25 READ A, BS, C%, Fl, R2, B(25) 10.1 


Statement Formats and Examples 


DATA 
line number 


399 
RESTORE 
line number 
125 
PRINT 


{line number} 


Section 
3.3.1 
DATA <list of values> 5.3 
DATA 4.3, "STRING",85,49,75.94,19 6.3 
Scdecl 
RESTORE 10.2 
RESTORE 


PRINT{{#<exp>, }<list>} 


25 PRINT !GENERATES CR/LF 
75 PRINT "BEGINNING OF OUTPUT";1,A*I . 
45 PRINT #4,"“OUTPUT TO DEVICE"FNM(A)t2;B;A 10. 
PRINT USING 
{line number} PRINT {#<exp>, }USING <string>, <list> 10.4 
54 PRINT USING "##.##",A 
55 PRINT #3, USING"\\###.## \\#etttt","A=",A,"B=",B 
56 PRINT #7, USING BS,A,B,C 
INPUT 3.3.3 
line number} INPUT {#<exp>, }<list> 5.3 
25 INPUT "TYPE YOUR NAME ",AS$ 6.3 
55 INPUT #8, A, N, BS 9.2.3 
9.2.5 
9.4 
INPUT LINE 52-3 
Tine number} INPUT LINE {#<exp>,} <string> 10. 
49 INPUT LINE R$ 
75 INPUT LINE #1, ES 
NAME-AS 9.7 
{line number} NAME <string> AS <string> | 
455 NAME "NONAME" AS "FILE1<48>" 
270 NAME "DT4:MATRIX" AS "MATA1<48>" 
KILL 9.8 
{line number} KILL <string> 
45 KILL "NONAME" 
ON ERROR GOTO 8.4 
tine number ON ERROR GOTO {<line number>} 
18 ON ERROR GOTO 599 
525 ON ERROR GOTO !DISABLES ERROR ROUTINE 
526 ON ERROR GOTO @ !DISABLES ERROR ROUTINE 
RESUME 8.4.1 
Zine number RESUME {<line number>} 
189@ RESUME !OR RESUME @ ARE EQUIVALENT 
655 RESUME 299 
CHAIN 
line number CHAIN <string> {<line number>} 9.9 
375 CHAIN "PROG2.BAC" 
588 CHAIN "PROG3.BAC" 75 


Statement Formats and Examples Section 
STOP 3.9 
line number STOP 
75 STOP 
END 3.9 
line number END 
545 END 
Matrix Statements 
MAT READ 7.2 
tne number MAT READ <list of matrices> 
55 DIM A(2f), BS$(32), C%(15,19) 
99 MAT READ A, BS(25), C% 
MAT PRINT 7.3 
{Zine number} MAT PRINT{#<exp>,} <matrix name> 
1g DIM A (29), B(15,29) 
99 MAT PRINT A; {PRINT 19*19 MATRIX, PACKED 
95 MAT PRINT B(1G,5), !PRINT 19*5 MATRIX, FIVE 
!ELEMENTS PER LINE 
97 MAT PRINT #2, A; !PRINT ON OUTPUT CHANNEL 2 
MAT INPUT ; 7.4 
Zine number} MAT INPUT{#<exp>,} <list of matrices> 
1g DIM BS(49), F1%(35) 
28 OPEN "DT3:FOO" FOR INPUT AS FILE 3 
39 MAT INPUT #3, B4, F13% 
MAT Initialization 7.5 
ER 
{line number} MAT <matriz nane>=[cou] (déneneton(}) 
ID 
18 DIM B(15,18), A(1), C% (5) 
15 MAT C% = CON !ALL ELEMENTS OF C%(I)=1 
28 MAT B= IDN (19,19) !IDENTITY MATRIX 19*19 
95 MAT B = ZER(N,M) {CLEARS AN N BY M MATRIX 
Statement Modifiers (can be used in immediate mode) 
IF G2 751 
<statement> IF <eondttion> 
1g PRINT X IF X<o"g 
UNLESS 
<statement> UNLESS <conditton> 8.7.2 
45 PRINT A UNLESS A=9 
FOR 8.7.3 
<statement> FOR <var> = <exp> TO <exp>{STEP<exp>} 
75 LET BS(I) = "“PDP-11" FOR I = 1 TO 25 
88 READ A(I) FOR I=2 TO 8 STEP 2 
WHILE 8.7.4 


Manual 


<statement> WHILE <condittion> 


1g 


LET A(I) = FNX(I) WHILE I<45.5 


Statement Formats and Examples 


Manual 
Section 
UNTIL 8.7.5 
<statement> UNTIL <condttton> 
115 IF B @ THEN A(I)=B UNTIL ID5 
System statements 
<Line number> SLEEP <expresston> 8.8 
108 SLEEP 2 !IDISMISS JOB FOR 2 SEC. 
<Lline number> WAIT <expresston> 8.8 
525 WAIT A%+5 !tWAIT A%$+5 SEC. FOR INPUT 
Record I/O Statements 
<Lline number> LSET<string var>{,<string var>}=<string> 11.4.2 
98 LSET BS="XYz" 
<Line number> RSET<string var>{,<string var>}=<string> 11.4.2 


256 RSET CS="67896" 


<line number> FIELD#<expr>,<expr>AS<string var>{,<expr>AS<string var>} 
75 FIELD#2%,16% AS A$, 28% AS BS 11.4.1 


<Line number> GET#<expr>{,RECORD<expr>} 11.3 
188 GET#1%,RECORD 99% 


<lLine number> PUT#<expr>{,RECORD<expr>}{,COUNT<expr>} 11.3 
566 PUT#1%,COUNT 88% 


<Line number> UNLOCK#<expr> 12.2 
768 UNLOCK #3% 
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Command 


ASSIGN 


BYE 
CAT 


CATALOG 


COMPILE 


CONT 


DEASSIGN 


DELETE 


HELLO 


KEY 


APPENDIX B 


BASIC-PLUS COMMAND SUMMARY 


Explanation 


Used to reserve an I/O device for the use of 
the individual issuing the command. The speci- 
fied device can then be given commands only 
from the terminal which issued the ASSIGN. 


Indicates to RSTS that a user wishes to leave 
the terminal. Closes and saves any files re- 
maining open for that user. 


Returns the user's file directory. Unless an- 
other device is specified following the term 
CAT or CATALOG, the disk is the assumed device. 


Allows the user to store a compiled version of 
his BASIC program. The file is stored on disk 
with the current name and the extension .BAC. 
Or, a new file name can be indicated and the 
extension .BAC will still be appended. 


Allows the user to continue execution of the 
program currently in core following the execu- 
tion of a STOP statement. 


Used to release the specified device for use 
by others. If no particular device is speci- 
fied, all devices assigned to that terminal 
are released. An automatic DEASSIGN is per- 
formed when the BYE command is given. 


Allows the user to remove one or more lines 
from the program currently in core. Following 
the word DELETE the user types the line number 
of the single line to be deleted or two line 
numbers separated by a dash (-) indicating the 
first and last line of the section of code to 
be removed. Several single lines or line 
sections can be indicated by separating the 
line numbers, or line number pairs, with a 
comma. 


Indicates to RSTS that a user wishes to log 
onto the system. Allows the user to input 
project-programmer number and password. 


Used to re-enable the echo feature on the user 
terminal following the issue of a TAPE command. 
Enter with LINE FEED or ESCAPE key. 


Section in 
RSTS-11 System 
User's Guide 


2.6.3 


2.5.2 


2.3.3 


2.6.4 


2.6.2 


Command 


LENGTH 


LIST 


LISTNH 


NEW 


OLD 


RENAME 


REPLACE 


RUN 


RUNNH 


Explanation 


Returns the length of the user's current 
program in core, in 1K increments. 


Allows the user to obtain a printed listing 

at the user terminal of the program currently 
in core, or one or more lines of that program. 
The word LIST by itself will cause the list- 
ing of the entire user program. LIST followed 
by one line number will list that line; and 
LIST followed by two line numbers separated 
by a dash (-) will list the lines between and 
including the lines indicated. Several single 
lines or line sections can be indicated by 
separating the line numbers, or line number 
pairs, with a comma. 


Same as LIST, but does not print header con- 
taining the program name and current date. 


Clears the user's area in core and allows the 
user to input a new program from the terminal. 
A program name can be indicated following the 
word NEW or when the system requests it. 


Clears the user's area in core and allows the 
user to recall a saved program from a storage 
device. The user can indicate a program name 
following the word OLD or when the system re- 
quests it. If no device name is given, the 

file is assumed to be on the system disk. A 
device specification without a filename will 

cause a program to be read from an input-only 


Section in 
RSTS-11 System 
_User's Guide _ 


device (such as high-speed reader, card reader). 


Causes the name of the program currently in 
core to be changed to the name specified after 
the word RENAME. 


Same as SAVE, but allows the user to substitute 2.4.6 
a new program with the same name for an old pro- 


gram, erasing the old program. 


Allows the user to begin execution of the pro- 


gram currently in core. The word RUN can be fol- 


lowed by a file name in which case the file is 


loaded from the system disk, compiled, and run; 


alternatively, the device and file name can be 


indicated if the file is not on the system disk. 
A device specification without a file name will 


cause a program to be read from an input only 


device (such as high-speed reader, card reader). 


Same as RUN, but does not print header contain- 2.3.1 


ing the program name and current date. 


Command 


SAVE 


TAPE 


UNSAVE 
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Explanation User's Guide 
Causes the program currently in core to be 2.4.1 


saved on the system disk under its current 

file name with the extension .BAS. Where 

the word SAVE is followed by a file name or 

a device and a file name, the program in core 
is saved under the name given and on the de- 
vice specified. A device specification with- 
out a file name will cause the program to be 
output to any output only device (line printer, 
high-speed punch). 


Used to disable the echo feature on the user 2.6.1 
terminal while reading paper tape via the 
low-speed reader. 


The word UNSAVE is followed by the file name 2.4.5 
and, optionally, the extension of the file to 

be removed. The’ UNSAVE command cannot remove 

files without an extension. If no extension 

is specified, the source (.BAS) file is deleted. 

If no device is specified, the disk is assumed. 


Special Control Character Summary 


CTRL/C 


CTRL/O 


CTRL/U 


CTRL/Z 


ESCape or 
ALT MODE 
Key 


LINE FEED 
Key 


RETURN 
Key 


RUBOUT 
Key 


TAB or 
CTRL/I 


Causes the system to return to BASIC command 3.5 
mode to allow for issuing of further commands 
or editing. Echoes on terminal as +c. 


Used as a switch to suppress/enable output of 3.7 
a program on the user terminal. Echoes as to. 


Deletes the current typed line, echoes as tU 3.6 
and performs a carriage return/line feed. 


Used as an end-of-file character. 3.9 


Enters a typed line to the system, echoes on 3.2 
the user terminal as a $ character and does 
not cause a carriage return/line feed. 


Used to continue the current logical line on 3.3 
an additional physical line. Performs a 
carriage return/line feed operation. 


Enters a typed line to the system, results in a 3.1 
carriage return/line feed operation at the user 
terminal. 


Deletes the last character typed on that physi- 3.4 
cal line. Erased characters are shown on the 
teleprinter between back slashes. 


Performs a tabulation to the next of nine tab 3.8 
stops (eight spaces apart) which form the 
terminal printing line. 


APPENDIX C 


ERROR MESSAGE SUMMARY 


Wherever possible, RSTS follows an error message with the phrase 
AT LINE xxxx 


where xxxx is the line number of the statement which caused the error. 


For example: 


1g TALK 
ILLEGAL VERB AT LINE 19 
READY 


The additional message is not printed when no line number can be as- 


sociated with the error. 


TALK 
WHAT? 
READY 


An (SPR) in the description of any error message in this Appendix 
indicates an error which should never be seen by a user. If such a 
message is received, the user should document how he obtained the error 
and file a Software Performance Report with DEC, including the perti- 


nent output. 
C.1 USER RECOVERABLE ERRORS 


A (C) in the description of the error message indicates that pro- 
gram execution continues, following printing of the error message, 
if an ON ERROR GOTO statement is not present. Normally, execution 
terminates on an error condition, the error message is printed, and 
the system prints READY. The ERR column gives the value of the ERR 
variable (see Section 8.4). 


ERR Message Printed Meaning 
1 BAD DIRECTORY FOR DEVICE The directory of the device refer- 


enced is an unreadable format or an 
attempt was made to perform a direc- 
tory oriented access to a non- 
directory device. 


Cc-1 


ied 


RR Message Printed Meaning 


2 ILLEGAL FILE NAME The filename specified is not accept- 
able. It contains unacceptable char- 
acters or the filename specification 
format has been violated. 


3 ACCOUNT OR DEVICE IN USE Removal or dismounting of the account 
or device cannot be done since one 
or more users are currently using it. 


4 NO ROOM FOR USER ON DEVICE Storage space allowed for the current 
user on the device specified has been 
used or the device as a whole is too 
full to accept further data. 


5 CAN'T FIND FILE OR ACCOUNT The file or account number specified 
was not found on the device specified. 


6 NOT A VALID DEVICE Attempt to use an illegal or nonexis- 
tent device specification. 


7 I/O CHANNEL ALREADY OPEN An attempt was made to open one of 
the twelve I/O channels which had 
already been opened by the program. 
(SPR) 


8 DEVICE NOT AVAILABLE The device requested is currently 
reserved by another user. 


9 I/O CHANNEL NOT OPEN Attempt to perform I/O on one of the 
twelve channels which has not been 
previously opened in the program. 


10 PROTECTION VIOLATION The user was prohibited from perform- 
ing the requested operation because 
the kind of operation was illegal 
(such as input from a line printer) 
or because the user did not have the 
privileges necessary (such as delet- 
ing a protected file). 


11 END OF FILE ON DEVICE Attempt to perform input beyond the 
end of a data file. 

12 FATAL SYSTEM I/O FAILURE An I/O error has occurred on the sys- 
tem level. The user has no guarantee 


that the last operation has been 
performed. (SPR) 


13 USER DATA ERROR ON DEVICE One or more characters may have been 
transmitted incorrectly due to a par- 
ity error, bad punch combination on 
a card, or Similar error. 


14 DEVICE HUNG OR WRITE LOCKED User should check hardware condition 
of device requested. Possible causes 
of this error include a line printer 
out of paper or high-speed reader 
being off-line. 


15 KEYBOARD WAIT EXHAUSTED Time requested by WAIT statement has 


been exhausted with no input received 
from the specified keyboard. 


C-2 


ERR 


17 


18 


19 


20 


21 


22 


23 


24 


25 


26 


27 


28 


29 
30-41 


42 


43 


Message Printed 
NAME OR ACCOUNT NOW EXISTS 


TOO MANY OPEN FILES ON UNIT 


ILLEGAL SYS() USAGE 


DISK BLOCK IS INTERLOCKED 


PACK IDS DON'T MATCH 


DISK PACK IS NOT MOUNTED 


DISK PACK IS LOCKED OUT 
ILLEGAL CLUSTER SIZE 


DISK PACK IS PRIVATE 


DISK PACK NEEDS 'CLEANING' 


FATAL DISK PACK MOUNT ERROR 


I/O TO DETACHED KEYBOARD 


PROGRAMMABLE +C TRAP 


CORRUPTED FILE STRUCTURE 
not assigned 


VIRTUAL BUFFER TOG 


LARGL 


VIRTUAL ARRAY wOT ON DISK 


Cc 


Meaning 


An attempt was made to rename a 
file with the name of a file which 
already exists, or an attempt was 
made by the system manager to in- 
sert an account number whicn is 
already within the system. 


Only one open DECtape output file 
is permitted per DECtape drive. 
Only one open file per magtape 
drive is permitted. 


Illegal use of the SYS system func- 
tion. 


The requested disk block segment 
is already in use (locked) by some 
other user. 


The identification code for the 
specified disk pack does not match 
the identification code already on 
the pack. 


No disk pack is mounted on the 
specified disk drive. 

The disk pack specified is mounted 
but temporarily disabled. 
The specified cluster size is unac- 
ceptable. 


The current user does not have ac- 
cess to the specified private disk 
pack. 


Non-fatal disk mounting error; use 
the CLEAN operation in UTILTY. 
Fatal disk mounting error. Disk can- 


not be successfully mounted. 


I/O was attempted to a hung up 
dataset or to the previous, but now 
detached, console keyboard for the 
job. 


ON ERROR-GOTO subroutine was entered 
through a program trapped CTRL/C. 
See a description of the SYS system 
functicn. 


Fatal error in CLEAN operation. 


Virtual core buffers must be 512 
bytes long. 


A non-cisk device is open on the 
Charnel upon which the virtual ar- 
ray is referenced. 


3 


46 


47 


48 


49 


50 


51 


52 


53 


54 


55 


56 


57 


58 


Message Printed 
MATRIX CR ARRAY TOO BIG 


VIRTUAL ARRAY NOT YET OPEN 


ILLEGAL I/O CHANNEL 


LINE TOO LONG 


FLOATING POINT ERROR 


ARGUMENT TOO LARGE IN EXP 


not assigned 


INTEGER ERROR 


ILLEGAL NUMBER 


ILLEGAL ARGUMENT IN LOG 


IMAGINARY SQUARE ROOTS 


SUBSCRIPT OUT OF RANGE 


CAN'T INVERT MATRIX 


OUT OF DATA 


ON STATEMENT OUT OF RANGE 


Meaning 
In-core array size is too large. 


An attempt was made to use a virtual 
array before opening the correspond- 
ing disk file. 


Attempt was made to open a file on 
an I/O channel outside the range of 
the integer numbers 1 to 12. 


Attempt to input a line longer than 
255 characters (which includes any 
line terminator). Buffer overflows. 


Floating point overflow or under- 
flow. If no transfer is made to 
an error handling routine, a @ is 
returned as the floating point 
value. (C) 


Acceptable arguments are within the 
approximate range -89<arg<+88. The 
value returned is zero. (C) 


Attempt to use a number as an in- 
teger when that number is outside 
the allowable integer range. If 
no transfer is made to an error 
handling routine, a § is returned 
as the integer value. (C) 


Improperly formed input or value. 
For example, "1..2" is an improp- 
erly formed number. 


Negative or zero argument to log 
function. Value returned is the 
argument as passed to the function. 


(C) 


Attempt to take square root of a 

number less than zero. The value 
returned is the square root of the 
absolute value of the argument. (C) 


Attempt to reference an array ele- 
ment beyond the number of elements 
created for the array when it was 
dimensioned. 


Attempt to invert a singular or 
nearly singular matrix. 


The DATA list was exhausted and a 
READ requested additional data. 


The index value in an ON-GOTO or 
ON-GOSUB statement is less than one 
or greater than the number of line 
numbers in the list. 


C-4 


ERR Message Printed 

59 NOT ENOUGH DATA IN RECORD 
60 INTEGER OVERFLOW, FOR LOOP 
61 DIVISION BY ¢ 

C.2 NON-RECOVERABLE ERRORS 


Message Printed 
ARGUMENTS DON'T MATCH 


BAD LINE NUMBER PAIR 


BAD NUMBER IN PRINT-USING 


CAN'T COMPILE STATEMENT 


CAN'T CONTINUE 


CATASTROPHIC ERROR 


DATA TYPE ERROR 


DEF WITHOUT FNEND 


END OF STATEMENT NOT SEEN 


EXECUTE ONLY FILE 


Meaning 


An INPUT statement did not find 
enough data in one line to satisfy 
all the specified variables. 


The integer index in a FOR loop 
attempted to go beyond 32766 or 
below -32766. 


Attempt by the user program to 
divide some quantity by zero. 
no transfer is made to an error 
handler routine, a @ is returned 
as the result. (C) 


If 


Meaning 


Arguments in a function call do not 
match, in number or in type, the 
arguments defined for the function. 


Line numbers specified in a LIST or 
DELETE command were formatted incor- 
rectly. 


Format specified in the PRINT-USING 
string cannot be used to print one 
or more values. 


Program was stopped or ended at a 
spot from which execution cannot be 
resumed. 


The user program data structures are 
destroyed. This normally indicates 

a BASIC-PLUS malfunction and, if re- 
producible, should be reported to DEC 
on a Software Performance Report form. 
(SPR) 


Incorrect usage of floating-point, 
integer, or character string format 
variable or constant where some other 
data type was necessary. 


A second DEF statement was encoun- 
tered in the processing of a user 
function without an FNEND statement 
terminating the first user function 
definition. 


Statement contains too many elements 
to be processed correctly. 


Attempt was made to add, delete or 
list a statement in a compiled (.BAC) 
format file. 


C-5 


Message Printed 
EXPRESSION TOO COMPLICATED 


FIELD OVERFLOWS BUFFER 


FILE EXISTS-USE REPLACE 


FNEND WITHOUT DEF 


FNEND WITHOUT FUNCTION CALL 


FOR WITHOUT NEXT 


ILLEGAL CONDITIONAL CLAUSE 


ILLEGAL DEF NESTING 


ILLEGAL DUMMY VARIABLE 


ILLEGAL EXPRESSION 


ILLEGAL FIELD VARIABLE 


ILLEGAL FN REDEFINITION 


ILLEGAL FUNCTION NAME 


Meaning 


This error usually occurs when 
parentheses have been nested too 
deeply. The depth allowable is 
dependent on the individual expres- 
sion. 


Attempt to use FIELD to allocate 
more space than exists in the speci- 
fied buffer. 


A file of the name specified ina 
SAVE command already exists. In 

order to save the current program 
under the name specified, use the 
REPLACE command. 


An FNEND statement was encountered 
in the user program without a pre- 
vious DEF statement being seen. 


A FNEND statement was encountered 
in the user program without a pre- 
vious function call having been 
executed. Function has been placed 
incorrectly among executable state- 
ments or an extra FNEND statement 
has been found. 


A FOR statement was encountered in 
the user program without a corre- 
sponding NEXT statement to terminate 
the loop. 


Incorrectly formatted condition ex- 
pression. 


The range of one function definition 
crosses the range of another func- 
tion definition. 


One of the variables in the dummy 
variable list of a user-defined 
function is not a legal variable 
name. 


Double operators, missing operators, 
mismatched parentheses, or some 
similar error has been found in an 
expression. 


The FIELD variable specified is un- 
acceptable. 


Attempt was made to redefine a user 
function. 


Attempt was made to define a func- 
tion with a function name not sub- 
scribing to the established format. 


ILLEGAL 


ILLEGAL 


ILLEGAL 


ILLEGAL 


ILLEGAL 


ILLEGAL 


ILLEGAL 


ILLEGAL 


INCONSISTENT FUNCTION USAGE 


INCONSISTENT SUBSCRIPT USE 


Message Printed 
IF STATEMENT 


IN IMMEDIATE MODE 


LINE NUMBER(S) 


MAGTAPE() USAGE 


MODE MIXING 


STATEMENT 


SYMBOL 


VERB 


K OF CORE USED 


LITERAL 


STRING NEEDED 


MATRIX DIMENSION ERROR 


MATRIX OR ARRAY WITHOUT DIM 


MAXIMUM CORE EXCEEDED 


MISSING SPECIAL FEATURE 


Meaning 
Incorrectly formatted IF statement. 


User issued a statement for execu- 
tion in immediate mode which can 
only be performed as part of a pro- 
gram, 


Line number reference outside the 
range 1<n<32767, 


Improper use of the MAGTAPE function. 


String and numeric operations cannot 
be mixed. 


Attempt was made to execute a state- 
ment that did not compile without 
errors. 


An unrecognizable character was en- 
countered. For example, a line con- 
sisting of a # character. 


The BASIC verb portion of the state- 
ment cannot be recognized. 


A function is being redefined in a 
manner inconsistent in the number or 
type of arguments with one or more 
calls to that function existing in 
the program. 


A subscripted variable is being used 
with a different number of dimensions 
from the number with which it was 
originally defined. 


Message printed by LENGTH command, 
preceded by the appropriate number 
describing the user program currently 
in core to the nearest 1K. 


A variable name was used where a 
numeric or character string was 
necessary. 


Attempt was made to dimension a 
matrix to more than two dimensions, 
or an error was made in the syntax 
of a DIM statement. 


A matrix or array element was ref- 
erenced beyond the range of an 
implicitly dimensioned matrix. 


User program grew to be too large 
to run or compile in the area of 
core assigned to each user at the 
given installation. 


User program employs a BASIC-PLUS 
feature not present on the given 
installation. 


C-7 


Message Printed 


MODIFIER ERROR 


NEXT WITHOUT FOR 


NO LOGINS 


NOT A RANDOM ACCESS DEVICE 


NOT ENOUGH AVAILABLE CORE 


NUMBER IS NEEDED 


1 OR 2 DIMENSIONS ONLY 


ON STATEMENT NEEDS GOTO 


PLEASE SAY HELLO 


PLEASE USE THE RUN COMMAND 


PRINT-USING BUFFER OVERFLOW 


PRINT-USING FORMAT ERROR 


PROGRAM LOST-SORRY 


REDIMENSIONED ARRAY 


RESUME AND NO ERROR 


Meaning 


Attempt to use one of the statement 
modifiers (FOR, WHILE, UNTIL, IF, 
or UNLESS) incorrectly. 


A NEXT statement was encountered in 
the user program without a previous 
FOR statement having been seen. 


Message printed if the system is 
full and cannot accept additional 
users or if further logins are dis- 
abled by the system manager. 


Attempt to perform random access I/0 
to a non-random access device. 


The already compiled user program is 
too large to run in the area of core 
assigned to each user at the given 
installation. 


A character string or variable name 
was used where a number was necessary. 


Attempt was made to dimension a matrix 
to more than two dimensions. 


A statement beginning with ON does 
not contain a GOTO or GOSUB clause. 


User not logged into the system has 
typed something other than a legal, 
logged-out command to the system. 


A transfer of control (as in a GOTO, 
GOSUB or IF-GOTO statement) cannot 
be performed from immediate mode. 


Format specified contains a field too 
large to be manipulated by the PRINT- 


USING statement. 


An error was made in the construction 
of the string used to supply the out- 
put format in a PRINT-USING statement. 


A fatal system error has occurred 
which caused the user program to be 
lost. 


Usage of an array or matrix within 
the user program has caused BASIC- 
PLUS to redimension the array im- 
plicitly. 


A RESUME statement was encountered 
where no error had occurred to cause 
a transfer into an error handling 
routine via the ON ERROR-GOTO state- 
ment. 


c-8 


Message Printed 


RETURN WITHOUT GOSUB 


STATEMENT NOT FOUND 


STOP 


STRING IS NEEDED 


SYNTAX ERROR 


TEXT TRUNCATED 


TOO FEW ARGUMENTS 


TOO MANY ARGUMENTS 


UNDEFINED FUNCTION CALLED 


WHAT? 


WRONG MATH PACKAGE 


Meaning 


RETURN statement encountered in the 
user program without a previous 
GOSUB statement having been executed. 


Reference is made within the program 
to a line number which is not within 
the program. 


STOP statement was executed. The 
user can usually continue program 
execution by typing CONT and the 
RETURN key. 


A number or variable name was used 
where a character string was neces- 
sary. 


BASIC-PLUS statement was incorrectly 
formatted. 


No BASIC-PLUS statement can be more 
than 255 characters long. 


The function has been called with 
a number of arguments not equal to 
the number defined for the function. 


A user-defined function may have up 
to five arguments. 


BASIC-PLUS interpreted some state- 
ment component as a function call 
for which there is no defined func- 
tion (system or user). 


Command or immediate mode statement 
entered to BASIC-PLUS could not be 
processed. Illegal verb or improper 
format error most likely. 


Program was compiled with an incom- 
patible version of RSTS. Program 
source must be recompiled. 


C.3 SYSTEM IDENTIFICATION MESSAGE 


ERR code @ is associated with the system installation name 


for use by the system programs. 


APPENDIX D 
BASIC-PLUS CHARACTER SET 


D.1 BASIC-PLUS CHARACTER SET 
re ay 
User program statements are composed of individual characters. 


Allowable characters come from the following character set: 


A through 2Z 
g through 9 
Space 
Tab 
and the following special symbols and keys: 


Key 
$ Used in specifying string variables (Section 5.1), 
or as the System Library file designator (RSTS-1ll System 
User's Guide). 
% Used in specifying integer variables (Section 6.1). 
Lod Used to delimit string constants, i.e., text 
strings (Section 5.1). 
! Begins comment part of a line (Section 3.1). 
Separates multiple statements on one line 
(Section 2.3.1). 
# Denotes a device or file # name, or is used as an 
output format effector (Chapter 7 and Section 19.4). 
P Output format effector and list terminator 
(Section 3.3). 
i Output format effector (Section 3.3). 
LINE When used at the end of a line, indicates that 
FEED the current statement is continued on the next 
line (Section 2.3.2). 
() Used to group arguments in an arithmetic ex- 
pression (Section 2.5). 
j Used to group project-programmer number. 
<> Used to delimit file protection codes. 
+ - Arithmetic operators (Section 2.5.3). 
e / 4 
= Replacement operator (Section 3.2). 
Logical equivalence operator (Section 2.5.4). 
< Logical "less than" operator (Section 2.5.4). 
> Logical "greater than" operator (Section 2.5.4). 


Logical "approximately equal to" Operator (Section 2.5.4). 


D-1 


D.2 ASCII CHARACTER CODES 


ASCII RSTS Decimal ASCII RSTS 
Character Usage Value Character Usage 


, 


Backslash Vertical Line 


@ 
A 
B 
Cc 
D 
E 
F 
G 
H 
I 
J 
K 
L 
M 
N 
Oo 
P 
Q 
R 
S 
T 
U 
Vv 
W 
x 
Y 
Z 
[ 
‘N 
} 


Pe—ANS KE PCE PHURQVOBD SHAUL TAMOAATD 


Tilde 
RUBOUT 


D.3 CARD CODES 


The RSTS card driver can be configured for one of three different 
punched card codes. These are: DEC#29 codes, DEC#26 codes and 1491 
(EBCDIC) codes. The RSTS-11 DEC#29 and DEC#26 codes are the same as 
the DOS-11 card codes. The particular set of codes used on the system 
is determined by the system manager. In all cases, the end-of-file 
(EOF) card must contain a 12-11-9-1 punch or a 12-11-@-1-6-7-8-9 punch 
in column @. 


CHARACTER ASCII, , DEC@29 DECA26 1461 | CHARACTER ASCII,,  DEC#29  —DEC#26 1481 


UNUSED 


{oe} 

& 

Ld ee ell oe eo) 
NNN p tw 

is 

| aol god Ox eel eel well oll ool Oo 8) 
FPNNNNNNN jp tw 

rs 


Ps + ten =m © 1H tH 
alll ell aed aol seed eel cel oad 
FP NMUNNNNNNNDND 


CAAIKDUBWNHHODMDUKUAWHH 
WDIDNEWNEOMIKDUAW yp 
WCMDIDUEBWNHPODIKDUBWDH LE 


"“ODMDIHUNAWHEWK 
WNH®RW 


QVQVWRQANQ LS 
Cau HU WP 


FPrYrmMUOWNHA UA 
bh 


to 
oo 
wm 


@ 
A 
B 
Cc 
D 
E 
F 
G 
H 
a 
J 
K 
L 
M 
N 
O 
P 
Q 
R 
Ss 
T 
U 
V 
W 
x 
Y 
Z 
[ 
\ 
] 

4 
+ 


UV HW A se 
BRQWOHH DAW MAYIKHUA 
DOrFArRN 

NU A 


EOF is 12-11-f-1 punch or a 12-11-9-1-6-7-8-9 punch. 


D.4 RADIX-58 CHARACTER SET 


Radix-5g 

Character ASCII Octal Equivalent Eguivalent 
space 4g g 

A-Z 191 - 132 1 - 32 

$ 44 33 

é 56 34 
unused 35 

g-9 69 - 71 36 - 47 


The maximum Radix-5#f value is, thus, 
47*597 + 47*59 + 47 = 174777 


The following table provides a convenient means of translating 
between the ASCII character set and its Radix-5f equivalents. For 
example, given the ASCII string X2B, the Radix-5f equivalent is 
(arithmetic is performed in octal): 


X = 113999 
2 = $9249p 
B= S999G2 
X2B = 115492 


Radix-5f Character/Position Table 


Single Char. 
or Second Third 
First Char. Character Character 


31, 1 
ss poet 


BIBI5o 
666126 


UNK KX ESECCHNDONOZEOrAUHMAAMOOWy 
"ON KKH ESCCHNDONOZEZOHRGOHRANHMUOWy 
OUNKKXEQCGCHNDONOBZErRGUHTMAHoONWY 


CDBDIHUPWNEHD 
WOWYWNAHAM PWN RQ 


6830630 O68047 


WONTON US WD FQ 


1717668 


APPENDIX E 


VIRTUAL ARRAY FACILITY 


The RSTS~11 virtual array facility provides the means for a 
BASIC-PLUS program to operate on data structures that are too large 
to be accommodated in core at one time. To accomplish this, RSTS-11l 
uses the disk file system for storage of data arrays, and only main- 
tains portions of these files in core at any given time. 


An essential difference between real arrays and their virtual 
counterparts is the order in which array elements are referenced. 
In real arrays, the referencing algorithm has no effect on the time 
it takes to accomplish the references; while for virtual arrays, this 
order can have a significant effect on the program execution time. 
This Appendix describes the algorithms used in the RSTS-11 virtual 
array processor, in order that users concerned with efficiency can 
optimize their use of this facility. 


Each RSTS-1l1 disk file appears to the user program as a con- 
tiguous sequence of 256-word records. Any position in a file can 
be specified internally with a two-component address; the first part 
being the relative record within the file,and the second being the 
position of the item within the block. One of the functions of the 
virtual array processor is to transform, or map, each virtual array 
reference into its corresponding file address. 


Virtual arrays are stored as unformatted binary data. This 
means that no I/O conversions (internal form-to-ASCII) need be per- 
formed in storing or retrieving elements in virtual storage. Thus, 
there is no loss of precision in these arrays, and no time wasted 


performing conversions. 


All references to virtual arrays are ultimately located via 
file addresses relative to the start of the file. No symbolic in- 
formation concerning array names, dimensions, or data types is stored 
within the file. Thus, different programs may use different array 
names to refer to the data contained within a single virtual array 
file. The user must be cautious in such operations, since it is 
his responsibility to ensure that all programs referencing a given 
set of virtual arrays are referencing the same data. Consider the 


following example: 


Program ONE contains 


1g DIM#1,X(1f) ,Y (18) 
29 OPEN "FILE" AS FILE 1 


Program TWO contains 


1g DIM#1,2(19) ,X(1f) 
28 OPEN "FILE" AS FILE 1 


Whenever program TWO references the array Z, it is using the data known 
to program ONE as array X. Both X and Z are the first arrays in their 
declarations, both contain floating-point data, and both are 11 elements 
(X(J),...,X(1f)) long. These two arrays, then, correspond in position, 
type, and dimension. 


References to the array X (in ONE) and to the array X (in TWO) 
do not refer to the same data, even though both are using the same 
virtual file (FILE). The concept of using relative position, rather 
than name, to identify data items is familiar to users of the FORTRAN 
common facility. 


Within a single BASIC-PLUS program it is possible to open a single 
virtual core array file twice on the same channel for the purpose of 
reallocating the data within the file. For example: 

145 OPEN "DATA" FOR INPUT AS FILE 1 

158 DIM#1, AS(1f)=4 

155 DIM#1, BS$(4)=16 
The program now has access to the file DATA through both the array AS 
and the array B$. Each element of B$ contains four elements of A$ 
(BS(g) is equivalent to the elements A$(f) through A$(3), etc.). Note 
that the file is open for input only and that the two DIM# statements 
reference that file on a single channel number (#1 in this case). 


Note also that the two statements: 
75 DIM#1, A(19) 
89 DIM#1, B(19) 
are not equivalent to the statement: 
98 DIM#1, A(1f),B(1f) 


In the first case the arrays A and B are equivalent to each other and 
constitute the first array in the file open on channel 1. In the 


second case the arrays A and B are defined as both existing in the 
file open on channel 1. 


CAUTION 


The user is advised not to open a single file 
under two different channel numbers. For ex- 
ample: 


5@ OPEN "VALUES" AS FILE 1 
55 OPEN "VALUES" AS FILE 2 


1g DIM#1; x$(29) 
195 DIM#2, YS (2g) 


causes two buffers to be created for the stor- 
age of input to/from channel 1 and to/from chan- 
nel 2. Data output to channel 1 is not avail- 
able to channel 2, etc. 


E.1 ARRAY STORAGE 


Any data element in a virtual array is completely contained 
within a single segment (256 words) of disk storage. This restric- 
tion has no effect on integers and floating-point items, where the 
size of data items is fixed (l-word integer, 2- or 4-word floating 
point numbers), but does limit the maximum length of a virtual 
string to 512 characters (512 bytes). The number of data elements 
stored in each disk segment is a function of the size of each ele- 
ment. For virtual strings, the number of elements is also related 
to the maximum string length specified in the DIM# statement. The 
size of a virtual string is defaulted to 16 characters, and can be 
specified as: 2, 4, 8, 16, 32, 64, 128, 256, or 512. Table E-1 
indicates the number of array elements stored in each segment of a 


virtual file. 


Table E-1l 


Virtual Array Storage Capabilities 


Number of Elements 
Data Type per Segment 
Integer (%) 
2-Word Floating Point 
4-Word Floating Point 
String (S$) 


(where the maximum length = 


Strings in virtual storage occupy pre-allocated space in the 
virtual file, and thus differ from strings in core storage, where 
space is allocated dynamically. A disk segment containing virtual 
strings can be considered to be a succession of fields, each of the 
maximum string length. When a virtual string is assigned a new value, 
it is stored left-justified in the appropriate field. If the new 
string value is shorter than the maximum length, the remainder of the 
field is filled with zeros. When the string is retrieved, its length 
is computed as the maximum string length minus the number of zero- 
filled bytes. 


E.2 TRANSLATION OF ARRAY SUBSCRIPTS INTO FILF ADDRESSES 

In order to translate an array subscript into a file address, 
RSTS-11 computes (a) the relative distance from the specified item 
to the first item in the array, and then adds (b) the relative dis- 
tance from the first element of the array to the first item in the 
file. The first quantity (a) is computed from the array subscript 
and the number of elements per block, as shown in Table E-l. The 
second number (b) is a constant for each array in a file, and is 


computed from the parameters specified in the DIM# statement. 


Since the DIM# statement contains the only information used to 
define the structure of a file, it is possible for the user to speci- 


fy different accessing arrangements for the same file in one or more 


programs. For example, the user can reference the same data as 
either a series of 32-byte strings (A2$) or 16-byte strings (Al1$), 
with the following statements: 


19 DIM #1,A1$(1999) = 16 !16 CHARACTER STRINGS. 
28 DIM #1,A2$(5@0) = 32 !32 CHARACTER STRINGS. 
38 OPEN 'FIL1' AS FILE 1 !VIRTUAL ARRAY FILE. 


The user should keep in mind that in BASIC-PLUS, as in most 
BASICs, array subscripts begin with @, not l. An array with di- 
mension n, or (n,m) actually contains n+l, or [(n+1)*(m+1)] elements. 


User programs may define two-dimensional virtual arrays as 
well as singly dimensioned ones. Two-dimensional arrays are stored 
on disk (and in core) linearly, row-by-row. Thus, in the case of 
an array X(1,2), the array appears logically as: 


while physically it is stored as: 


lowest address 


highest address 


If a virtual array is to be referenced sequentially, it is 
usually preferable to reference the rows, rather than the columns, 
in sequence. Consider the case in which it is necessary to com- 
pute the sum of each row and column in two dimensional virtual 
array. Program ONE below does this far more efficiently than pro- 
gram TWO below: 


1f REM PROGRAM 'ONE' TO COMPUTE SUMS EFFICIENTLY 
29 REM 'AR' CONTAINS VIRTUAL ARRAY 

39 REM R(I) IS SUM OF ROW I 

48 REM C(J) IS SUM OF COLUMN J 

59 DIM #1,A(19,59) !1f8 ROWS,5@ COLUMNS 


628 DIM R(19), C(5%) 


7@ OPEN 'AR' AS FILE 1 !OPEN VIRTUAL FILE 

89 MAT R = ZER {INITIALIZE SUM 

99 MAT C = ZER 
199 FOR I = 1 TO 19 !OPERATE ROW BY ROW 
119 FOR J = 1 TO 59 {DO EACH COLUMN IN ROW 
129 R(I) = R(I) + A(I,J) !TOTAL ACROSS ROW 
138 C(J) = C(J) + ACI,J) !TOTAL DOWN COLUMN 
149 NEXT J !NEXT COLUMN IN ROW 
159 NEXT I !NEXT ROW 
169 MAT PRINT R; !PRINT ROW TOTALS 
178 MAT PRINT C; !PRINT COLUMN TOTALS 
268 CLOSE 1 
999 END 


19 REM PROGRAM 'TWO' HAS INEFFICIENT USE OF VIRTUAL CORE 


28 REM 'AR' CONTAINS VIRTUAL ARRAY 
39 REM R(I) CONTAINS SUM OF ROW I 

49 REM C(J) CONTAINS SUM OF COLUMN J 
59 DIM #1,A(19,59) 119 ROWS, 59 COLUMNS 


69 DIM R(1f), C(59) 

79 OPEN 'AR' AS FILE 1 

89 MAT R = ZER 

99 MAT C = ZER 

95 REM - REFERENCING ARRAY ELEMENTS DOWN THE 
96 REM ~ COLUMNS CAUSES EXTRA DISK REFERENCES 


199 FOR J = 1 TO 59 !OPERATE ONE COLUMN AT A TIME 
119 FOR I = 1 TO 1g !AND EACH ROW IN COLUMN 

126 R(I) = R(I) + A(I,J) !TOTAL ACROSS ROW 

138 C(J) = C(J) + A(I,d) !TOTAL DOWN COLUMN 

149 NEXT I !INEXT ROW IN COLUMN 

158 NEXT J INEXT COLUMN 


169 MAT PRINT R; 


179 MAT PRINT C: 
268 CLOSE 1 
999 END 


In virtual core arrays it is permissible to have two (or 
more) arrays sharing the same file. That is, the following DIM# 
statement is perfectly legal: 


1gg DIM#1,A(19PP) ,B% (999) ,C (1 47H) 


The matrix B% begins immediately after the 1f##th element 
of A and the matrix C begins immediately after B%(999). There- 
fore, the disk layout is as follows: 
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A(959) 
BS (@) 
BS (1) 


| CP) 
e 


ce 
C(999) 
= 


Figure E-1l Virtual Array File Layout 


There is, however, an exception to this rule. Elements in string 
arrays are allocated a fixed number of bytes in the disk file. This 
is either 2, 4, 8, 16, 32, 64, 128, 256 or 512 bytes of storage. A 
single string element must not cross a disk block boundary (where 
each disk block contains 512 bytes or 256 words). Consider the 
following case: 


198 DIM A%(2) ,BS(169f)=4 


The first three words of the disk block are allocated to Ag. 
If the array B$ were to begin immediately after A%, one of the ele- 
ments of BS would cross a block boundary. Hence, BS begins at the 
start of the second block in the file rather than immediately after 
Ag, 


The rule can be stated as follows: When more than one array 
is assigned to a single virtual array file, each array begins imme- 
diately following the last element of the preceding array unless 
such an allocation would cause an element of the array to be split 
across two disk blocks, in which case the array begins at the start 
of the next block of the file, and the remaining words of the cur- 
rent block are unused. 


E.3 ACCESS TO DATA IN VIRTUAL ARRAYS 


Only a portion of a virtual array is in core at any given time. 
This data is transferred directly between the disk and an I/O buf- 
fer in the user core area, created when the OPEN statement is exe- 
cuted. This buffer must be 256 words (one segment) long, and 
may not be specified as several segments with the RECORDSIZE option 
in the OPEN statement. For each virtual array file, RSTS-11 
notes (1) the segment of the file in the buffer, and (2) whether 
the data in the buffer has been modified since it was read into 


core. 


After RSTS-11 translates a virtual array address into a file 
address, it checks whether the segment containing the referenced 
item is currently in the buffer. If the necessary segment is pre- 
sent the reference proceeds; but if not, another portion of the 
file is read into the buffer. If the current data in the buffer 
has been altered, it is necessary to rewrite this data on the disk 


prior to reading new data into the buffer. 


The referencing algorithm, which minimizes the number of disk 
memory accesses generated when handling virtual arrays, is flow- 


charted in Figure E-2. 


E.4 ALLOCATING DISK STORAGE TO VIRTUAL FILES 


The dimensions indicated in a DIM# statement set maximum .allow- 
able values for subscripts, and are not used to compute the initial 
size of the virtual file to be allocated on disk. Instead, the 
file is created with an initial length of § segments, and segments 
are appended to the file, to accommodate the highest referenced file 
address in the array. This permits a user to specify array dimen- 
sions larger than required at the time the program is written; such 
programs may eventually operate on larger arrays without modification, 


and without tying up disk storage unnecessarily. 


Areas of unallocated disk storage are found only at the end of 
a file. 


As segments are appended to a file, their contents are not 
initialized to zero. The data previously recorded in a segment (when 
it was part of another file) is available to the new owner of the 
segment. Users whose files contain confidential information should 
explicitly overwrite all data in such files, prior to file deletion, 


in order to protect data contained therein. 
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Figure E-2 Virtual Array Accessing Algorithm 
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If a user wishes to override the dynamic virtual array alloca- 
tion, he should reference the last element in the virtual array file. 
This causes all segments in the file, up to and including the last, 
to be allocated. As noted above, the contents of these segments as 
appended to the file is unknown. Using the MAT ZER command is 
advisable if the program depends on array values being initialized 
to a known (zero) quantity. 


APPENDIX F 


RSTS FLOATING-POINT AND INTEGER FORMATS 


F.1 FLOATING-POINT FORMATS 


RSTS systems use two standard floating-point packages: th 


c) 


single precision, two-word package or the double precision, four-word 
package. The determination of which package will be used is made by 
the system manager at the time the RSTS Monitor is built. 


The single precision format provides economical storage, while 
the double precision format is used for high accuracy. The single 
precision format provides up to 24 bits or approximately seven decimal 
digits of accuracy. The magnitude range lies between §.14 x 19738 
and 1.7 x 1938, Double precision calculations have a precision of 56 
bits or approximately fifteen decimal digits, with magnitudes in the 


same range as for single precision format. 


15 14 7 6 


SINGLE PRECISION FORMAT (2 WORD) 


oO 


wordt2: low-order mantissa 
word+4: lower-order mantissa 
word+6: lowest-order mantissa 


DOUBLE PRECISION FORMAT (4 WORD) 


The exponent is stored in excess 128 (2985) notation. Exponents 
from -128 to +127 are represented by the binary equivalent 
of @ through 255 (@ through 3779). Fractions are represented in sign 
magnitude notation with the binary radix point to the left. Numbers 
are assumed to be normalized and, therefore, the most significant bit 
is not stored because it is redundant (this is called "hidden bit 
normalization"); it is always a.l unless the exponent is @ (corre- 


sponding to 27128) in which case it is assumed to be 9. The value @ 
is represented by two or four words of zeroes. For example: +1 would 


be represented by: 


word: G49 2989 
word+2: GASPBO 


in the 2-word format, or: 


word: P48289 
word+2: PPGSPD 
wordt4: PESSSS 
wordté: PPGSIS 


in the 4-word format. -5 would be: 


word: 149649 
word+2: GPIABS 


in the 2-word format, or: 


word: 149646 
word+2: PIGIPS 
wordt+4: GIPLBB 
word+6: PIEBIS 


in the 4-word format. 


While it is generally possible to run programs written on one 
RSTS system on another RSTS system, certain restrictions apply if the 
math packages are not the same. These are: 


a. Programs depending on 4-word accuracy cannot be run 
with the 2-word package. 


b. .BAC compiled programs can not be interchanged. 
The program source file must be recompiled. 


c. Floating-point virtual core array file formats are 
not compatible between math packages. 


d. Programs using the RECORD I/O functions CVTSF and 
CVTFS are not compatible between math packages. 


F.2 INTEGER FORMAT 


15 14 g 


Integers are stored in a two's complement representation. Integer 
values must be in the range -32768 to +32767. For example: 


+22 
-7 


BI9026 g 
177771. 


As a rule, an integer value is assumed by RSTS only where a con- 
stant or variable name is followed by a % character. Otherwise, con- 


Stants and variables are assumed to be floating-point values. 
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Account numbers, see project- 
programmer number 
AND, 2-9, 3-14 
Angle brackets (<>), 
Approximately equal (= 
Arithmetic operators, 
with matrices, 7-6 
Array variables, 3-19, 
character string, 5-3 
default values, 3-21 
virtual core, 9-17 
zero elements, 3-21, 
see also matrices 
ASCII 
conversions, 
formatted I/O, 
table, 5-2 
Assignable devices, 
Asterisk (*), 10-9 


1-3 
=), 2-9 
2-7 


3-20 


7-5, 7-7 


5-5 
9-11 


9-7 


BASIC 

language and interpreter, 
Backslash, 10-8 
Backspace MAGTAPE function, 
Blocks, disk, 9-9 
Braces ({}), 1-3 
Brackets, see angle brackets, 

square brackets, braces 


1-4 


12-11 


Calculations, immediate mode, 4-1 
Card reader 
carriage return/line feed, 12-15 
EOF card, 12-15 
illegal punches, 12-16 
trailing blanks, 12-15 
CHAIN statement, 9-16, 9-23 
CHANGE statement, 5-5 
Channel numbers 
FIELD, 11-5 
user terminal, 9-5, 9-11, 9-13, 
9-15 
virtual array, 9-17, 9-19 
Character strings, 5-1 
constants, 5-2 
conversions to/from ASCII values, 
5-5 
functions, 5-11, 5-13 
output by PRINT, 3-7, 3-8 


relational operators, 5-4 
size, 5-4 
string input, 
string output, 
subscripted variables, 
user-defined, 8-3 
variables, 5-2 
virtual core arrays, 


5-8 
5-11, 10-5 
5-3 


9-18 


IND 


EX 


CLOSE statement, 9-15 


file structured magtape, 1 

non-file structured, 12-8 

Record I/O, 11-2 

virtual array files, 9-20 
CLUSTERSIZE option, 9-9, 1-1 
Commands, 1-4 
Commas 

in MAT PRINT, 7-2 

in PRINT, 3-7, 3-9, 10-6 

in PRINT-USING, 10-11 
Comments, 3-1 

DATA statement, 3-5 
Conditional FOR loops, 2-8, 
Conditions, 3-13 

see also relational expres 


and logical expressions 

Conformable matrices, 7-6 
CON function, 7-5 
Constants, 

character string, 

integer, 6-1 

numeric, 2-5 
CONT command, 4-1, 
Control variable, 
Conventions, manual, 
COUNT option, 11-4 
CRT display terminals, 
CTRL/C, 4-2 
CTRL/Z, 9-16 
CVT conversion functions, 


5-2 


4-2 
3-17, 3-19 
1-3 


12-18 
11 


Data files, see files, data 
Data pool, 10-1 
DATA statement, 3-2, 3-33, 5 
character strings in, 5-8, 
10-1 
comments, 3-5, 10-1 
data pool storage, 
immediate mode, 4-3 
Simplest form, 3-4 
Debugging, 4-l, 4-2 
DEF statement, 3-27 
immediate mode, 4-3 
multiple line, 8-1 
Density and Parity, MAGTAPE 
function, 12-11 
Device buffer sizes, default, 


10-1 


Device designator, 9-2 

Devices, assignable, 9-7 

DIM statement, 3-21 
immediate mode, 4-3 


Placement on line, 3-22 
placement in program, 3-22 
DIM# statement, 9-17 
Disks, 12-1 
blocks, 9-9 
UPDATE, 12-2 
virtual core, 9-17, E-1l 


2-7 


0 


8-15 


sions 


-9 


-9, 10-1 
5-9, 


Display terminals, 12-18 


Dollar sign character ($), 9-3, 
10-11 
DOos-11 
DECtape interchange, 9-3 
magtape interchange, 9-3, 12-5, 
12-6 
Dummy variables or arguments, see 
variables 
E format numbers, 2-6 
END statement, 3-33, 3-34 
EOF (end-of-file), 9-16, 12-4, 12-5 
punched card, 12-15 


write EOF MAGTAPE function, 12-10 
EQV, 2-10, 3-14 
ERL variable, 8-11 
ERR variable, 8-6 
values, 8-7 through 8-9 
Errors 
disabling error control, 8-10 
ERL variable, 8-11 
magtape, 12-14 
ON ERROR GOTO, 8-5 
program control of, 8-5 
user recoverable, 8-7 
Example BASIC program, 2-1 
Exclamation mark (!), 3-1, 10-7 
Exponential format output, 10-10 


2-5 
2-5 


Expressions, 
arithmetic, 
logical, 2-5 
relational, 2-9 


Extension format, 9-2 


FALSE, 6-3, 6-4 

FIELD statement, 11-5 

Filename format, 9-2 

Filename specification, complete, 


9-1, 9-12 
Files, data, 9-1 
formatted data, 9-li, li-i 
random access, 9-16, 11-1 


Record I/O, 11-1 
see also virtual array files 


Files, DECtape, 9-2 
Files, disk 
extending, 11-13 
improving throughput, 9-8, 9-11 
locked, 12-3 
[proj,prog], 9-3 
simultaneous multiple uses, 12-2 
UNLOCK, 12-3 
UPDATE mode, 12-2 
virtual core arrays, 9-17 
Files, magtape, 12-4 
CLOSE, 12-7 
file label, 12-6 
file structured, 12-5 
MODE option, 11-1 
non-file structured, 9-8, 12-6 
OPEN, 12-5, 12-7 
{[proj,prog], 9-3 


9-12 
9-2, 


File-structured devices, 
RECOUNT variable, 9-1, 
9-5 
FNEND statement, 8-1 
immediate mode, 4-3 
Formatted ASCII I/O, 
Form feed, line printer, 
12-17, 12-18 
FOR modifier, 8-19 
FOR statement, 3-16 
conditional loops, 2-8 
conditional termination, 
immediate mode, 4-3 
nesting loops, 3-18 
test condition, 3-16 
Functions 
conversion, 
mathematical, 
matrix, 7-5, 
print, 10-14 
recursive, 8-2 
string, 5-ll, 
user-defined, 
8-1 
XLATE, 


9-3, 


9-11 


12-16, 


8-15 


11-9 
3-22, 
7-7 


3-23 


5-13 


3-27, 5-11, 6-3, 


11-12 
11-2 


3-33 
4-3 


GET statement, 

GOSUB statement, 
immediate mode, 

GOTO statement 
conditional branch, 
immediate mode, 4-3 
unconditional branch, 


3-12 


3-11 


IDN function, 7-5 
IF clause, 2-8 
IF-GOTO statement, 


placement on line, 


3-12 
3-15 


transfer path, 3-15 
IF modifier, 8-18 
IF-THEN-ELSE statemen t, 8-12 
placement on line, 8-14 
statements following, 8-14 
IF-THEN statement, 2-8, 3-12 
placement on line, 3-15 


transfer path, 3-15 

Immediate mode, 4-1 
multiple statements per line, 4-2 
restrictions, 4-3 


IMP, 2-10, 3-14 
Implicit dimensions, 7-1 
In-core file window, 9-10 
Input 
character strings, 5-8 
integers, 6-2 
matrices, 7-2, 7-3 
see also READ, INPUT, and 
INPUT LINE 
INPUT LINE statement, 5-9, 10-4 
message output, 5-10 


INPUT statement, 3-9, 9-11, 10-3 
character string input, 5-9 
from data files, 9-11 
from non-terminal devices, 
message output, 3-11 
simplest form, 3-9 

Integer 
arithmetic, 6-1 
constants, 6-1 
I/O, 6-2 
user-defined functions, 8-3 
variables, 6-1 

Internal file designators, 
FIELD, 11-5 
user terminal, 
virtual array, 

Intrinsic functions, 

INT(X) function, 3-24 

Inversion of matrices, 7-7 

I/O, basic operations, 3-3 
complete discussion, Part III 
see also individual entries 

Italics, 1-3 


9-11 


9-5, 


9-13, 9-14 
9-17, 9-19 
see functions 


KILL statement, 9-22, 12-15 


LET statement, 3-2 
cautions, 11-8 
multiple variables, 3-3 
omitting LET, 3-3 
placement on line, 3-3 

Line, 1-4 


multiple statements on single, 2-3 


single statement on multiple, 2-3 


Line number, 1-3, 2-1 
Line printer 
LPFORM option, 12-16 


MODE option, 11-1 
special characters, 
Line terminators, 5-10 

Locked file, 12-3 
Logical 
expressions, 2-9, 2-10, 3-13 
operators, 2-9, 6-3 
variables, 6-3 
Loops, 3-13, 3-15 
conditional termination of, 
nested, 3-18 
LPFORM option, 
LSET statement, 


12-16 


8-15 


12-16, 12-18 


11-7, 


12-17, 
11-8 


Magnetic tape, 

Magtape 
error handling, 
file labels, 12-6 
file-structured, 
MODE, 12-3, 12-8 
non-file structured, 
status word, 12-13 

MAGTAPE function,12-9 through 12-13 


see magtape 
12-14 
12-4, 


12-4 


X-3 


9-11 


12-5, 12-6 


Mathematical functions, 3-22, 3-23 
Mathematical operators, 2-7 


MAT INPUT statement, 7-3, 10-4 
MAT PRINT statement, 7-2, 10-13 
MAT READ statement, 7-2, 10-2 
Matrices, 7-1 

calculations, 7-6 

conformable, 7-6 

functions, 7-7 

implicit dimensions, 7-1 


initialization, 7-5 


MAT INPUT, 7-3, 10-4 
MAT PRINT, 7-2, 10-13 
MAT READ, 7-2, 10-2 


redimensioning, 7-4 

square, 7-7 

storage, 7-1 

virtual core, 9-17 
Memory, conserving, 
Message output 

by INPUT, 3-11 

by PRINT, 3-8 


see programs 


Minus sign (-), 10-10 
MODE option, 11-1, 12-3, 12-8 
Modifiers, see statement modifiers 


Modules, arithmetic example, 3-29 
Multiple lines per statement, 2-3 
immediate mode, 4-2 


Multiple statement modifiers, 8-22 


NAME~-AS statement, 9-4, 9-21, 
9-23, 12-15 
Nesting 
functions, 8-l 
loops, 3-18 
subroutines, 3-34 
NEXT statement, 3-17 
immediate mode, 4-3 
9-track magtape, 12-8, 12-12 
Non-file structured devices, 
9-3, 9-5, 9-12 
RECOUNT variable, 
NOT, 2-9, 3-14 
Number format, output by PRINT 
statement, 3-6 
Numbers, 2-5 
E format, 2-6 
Number sign (#)., 


9-2, 


11-3 


10-8 


Off-line MAGTAPE function, 12-9 

OLD command, 3-34 

ON ERROR GOTO statement, 8-5 
disabling error routine, 8-10 
ON ERROR GOTO $, 8-10 
RESUME, 8-9 

ON-GOSUB statement, 98-4 

ON-GOTO statement, 8-3 

OPEN statement, 9-5, 9-6 
CLUSTERSIZE option, 9-9 
file-structured magtape, 
FOR INPUT, 9-6, 9-7 


12-5 


OPEN statement (cont.) Question mark (?), printed by 
FOR OUTPUT, 9-6, 9-7 INPUT, 3-11 
MODE option, 11-1, 12-3, 12-8 
non-file structured magtape, 12-7 


Record I/O, 11-1, 11-3, 11-4 Random access files, see virtual 
RECORDSIZE option, 9-7 array files 
user terminal, 9-13 RANDOM statement, 3-26 
virtual array file, 9-19 RANDOMIZE statement, 3-26 
Operators, READ statement, 10-1 
logical, 2-9 simplest form, 3-4 
mathematical, 2-7 Record I/O options, 11-1 
Matrix, 7-6 CLOSE, 11-2 
relational, 2-8 example, 12-4 
OR, 209, 3-14 FIELD, 11-5 
Output, LPFORM, 12-16 
character strings, 5-1ll LSET, 11-7, 11-8 
integers, 6-2 RSET, 11-7, 11-8 
matrices, 7-2 translation function, 11-12 
see also PRINT UPDATE, ll-1, 12-2 


RECORD option, 11-2, 11-4 
RECORDSIZE option, 9-7, 9-8, 


Pack cluster size, 9-9, 9-10 li-1, 11-3, 11-4, 11-5, 12-3 
Parentheses, 2-8 default device buffer sizer, 9-7 
Parity, 12-8 RECOUNT variable, 11-3 
Magtape error, 12-14 Relational 
set density and parity MAGTAPE expressions, 2-9, 2-10, 8-12, 
function, 12-11 8-18 through 8-21 
Percent sign (%), 6-1, 10-11 operators, 2-8 
Pound sign (#), 10-8 operators with character 
Precedence rules strings, 5-4 
complete, 3-14 REMARK statement, 3-1 
mathematical, 2-7, 2-8 RSET statement, 11-7, 11-8 
PRINT functions, 10-14 RESTORE statement, 3-5, 10-2 
PRINT statement, 3-6, 9-ll, 10-5 RESUME statement, 8-9 
character string format,3-8,10-5 RETURN statement, 3-33, 8-4 
comma, 10-6 immediate mode, 4-3 
message output, 3-8 Rewind and unload MAGTAPE function 
number format, 3-6 12-9 
output rules,. 10-6 Rewind MAGTAPE function, 12-10 
performing calculations, 3-6 RND function, 3-26 
semicolon, 10-6 RND(X) function, 3-25 


simplest form, 3-6 
suppress carriage return/line feed, 


3-9 SAVE comand, 3-34 
to data files, 9-11 Scientific notation, 2-6 
to non-terminal devices, 9-14 Semicolon 
without arguments, 3-6 in MAT PRINT, 7-2 
PRINT-USING statement, 10-7 in PRINT, 3-8, 3-9 
punctuation, 10-12 Set density and parity, MAGTAPE 
Print zones, 3-7 function, 12-il1 
Priorities, see precedence rules 7J-track magtape, 12-8, 12-11 
Private disks, 9-2,.12-1 SGN(X) function, 3-23 
Programs, 1-4 Single statement on multiple lines,2-3 
conserving memory space, 3-22 Skip record MAGTAPE function, 12-10 
debugging, 4-1, 4-2 SLEEP statement, 8-24 
line, 1-4 Space, conservation of, see programs 
Project-programmer number, 9-3 Spaces, 2-4 
Protection code, 9-3, 9-4, 9-6, Square brackets ([]), 1-3 
9-22, 9-23 Square matrix, 7-7 


Public disks, 9-2, 12-1 
PUT statement, 11-2 


Statement modifiers, 8-18 
FOR, 8-19 
IF, 8-18 
multiple, 8-22 
UNLESS, 8-19 
UNTIL, 8-21 
WHILE, 8-20 
Statements, 1-4, 2-3 


multiple on single line, 2-3 
single on multiple lines, 2-3 
Status (tape) MAGTAPE function, 
12-12 


Status word, magtape, 12-13 
STEP expression, 3-17, 8-15 
STOP statement, 3-34, 4-1 
String, see character string 
Subroutines, 3-32 
GOSUB, 3-32 
nesting, 3-32 
ON-GOSUB, 8-4 
Subscripts, 3-19, 3-20 
character string variables, 5-3 
default values, 3-21 
zero elements, 3-21 
Syntax, 2-1 
System functions, 8-22, 8-23 
Tabs, 2-4, 12-16 
Tape Status MAGTAPE function, 12-12 
Terminal input, see INPUT and 
INPUT LINE 
Terminals, 1-4 
Time sharing, 1-2 
Trailing minus sign, 10-10 
Transposition of matrices, 7-7 


TRUE, 6-3, 6-4 


Truth tables, 2-10 
UFD, 9-3, 9-9, 9-10 
Unary operators, 

minus, 2-7 

plus, 2-7 
Unconditional branch, 3-11 
UNLESS modifier, 2-8, 8-19 
UNLOCK statement, 12-3 


UNTIL modifier, 2-8, 8-15, 8-21 
Up-arrow (+), 10-10 
UPDATE option, 9-7, 12-2 


User-defined functions, 3-27 
function names, 3-27 
immediate mode, 4-3 
integer, 6-3 
multiple line, 
string, 5-11 

User File Directory, 


8-1 


see UFD 


Variables 
character string, 
dummy, 3-28, 8-1 
ERL, 8-11 
ERR, 8-6 
integer, 6-1 
logical, 6-3 
numeric, 2-6 
RECOUNT, 11-3 
subscripted, 3-19, 3-20, 5-3, 7-1 
subscripted and unsubscripted in 


5-2 


same program, 3-9, 5-3 
Virtual array files, 9-16 
example, 9-20 
extending file, 11-14 
opening, 9-19 


string storage, 9-18 
see also Appendix E 
Virtual data storage, 
array files 
VT@5 and VT#{6 display terminals, 


see virtual 


12-18, 12-19 
WAIT statement, 8-24 
WHILE modifier, 2-8, 8-15, 8-20 


Write end-of-file MAGTAPE function, 


12-10 . 
XLATE function, 11-12 
XOR, 2-9, 3-14 
ZER function, 7-5 
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